Package com.ibm.soa.parlayx21.presence

Presence.

See:
          Description

Interface Summary
PresenceConsumer The interface contains the operations for the presence consumer.
PresenceConsumer_RI  
PresenceConsumerHome  
PresenceConsumerService  
PresenceNotification The interface contains the operations for the presence notification.
PresenceNotification_RI  
PresenceNotificationHome  
PresenceNotificationService  
PresenceSupplier The interface containing the operations of the presence supplier.
PresenceSupplier_RI  
PresenceSupplierHome  
PresenceSupplierService  
 

Class Summary
ActivityValue This enumeration shows the user's current activity.
AttributeTypeAndValue  
AttributeTypeAndValue_Deser  
AttributeTypeAndValue_Helper  
AttributeTypeAndValue_Ser  
CommunicationMeans This structure describes on way of reaching the presentity.
CommunicationMeans_Deser  
CommunicationMeans_Helper  
CommunicationMeans_Ser  
CommunicationMeansType This enumeration lists communication means.
OtherValue This structure can be used for storing arbitrary data about a presentity.
OtherValue_Deser  
OtherValue_Helper  
OtherValue_Ser  
PlaceValue This enumeration shows the type of the user's current location.
PresenceAttribute Presence data published by a presentity and retrieved by watchers.
PresenceAttribute_Deser  
PresenceAttribute_Helper  
PresenceAttribute_Ser  
PresenceAttributeType The different types of attributes.
PresenceConsumerBindingStub  
PresenceConsumerProxy  
PresenceConsumerServiceInformation  
PresenceConsumerServiceLocator  
PresenceNotificationBindingStub  
PresenceNotificationProxy  
PresenceNotificationServiceInformation  
PresenceNotificationServiceLocator  
PresencePermission The answer from the service to the watcher in the notifySubscription operation.
PresencePermission_Deser  
PresencePermission_Helper  
PresencePermission_Ser  
PresenceSupplierBindingStub  
PresenceSupplierProxy  
PresenceSupplierServiceInformation  
PresenceSupplierServiceLocator  
PrivacyValue This enumeration shows the amount of privacy a user currently has.
SphereValue This enumeration shows the sphere within which the user acts.
SubscriptionRequest This structure is returned to the presentity by the Presence Web Service and contains the requesting watcher and the attributes he wants to subscribe.
SubscriptionRequest_Deser  
SubscriptionRequest_Helper  
SubscriptionRequest_Ser  
 

Package com.ibm.soa.parlayx21.presence Description

Presence.

Common Data Types

For common data types associated with this package see Common Data Types.

Scope

The present document is part 14 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 Presence 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.

References

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] ETSI TR 121 905: "Universal Mobile Telecommunications System (UMTS); Vocabulary for 3GPP Specifications (3GPP TR 21.905)".

[2] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes".

NOTE: Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.

[3] ETSI ES 202 391-1: "Open Service Access (OSA); Parlay X 2 Web Services; Part 1: Common".

[4] ETSI ES 202 915-14: "Open Service Access (OSA); Application Programming Interface (API); Part 14: Presence and Availability Management SCF (Parlay 4)".

[5] RFC 3856: "A Presence Event Package for the Session Initiation Protocol (SIP)". http://www.ietf.org/rfc/rfc3856.txt.

[6] Void.

[7] ETSI ES 202 391-13: "Open Service Access (OSA); Parlay X 2 Web Services; Part 13: Address List Management".

[8] IETF RFC 3265: "Session Initiation Protocol (SIP)-Specific Event Notification".

[9] Void.

[10] ETSI ES 202 391-8: "Open Service Access (OSA); Parlay X 2 Web Services; Part 8: Terminal Status".

[11] ETSI ES 202 391-9: "Open Service Access (OSA); Parlay X 2 Web Services; Part 9: Terminal Location".

Definitions and abbreviations

Definitions

For the purposes of the present document, the terms and definitions given in ES 202 391-1 [3] and the following apply:

applications: For Instant Messaging, Push to Talk, or call control and other purposes may become clients of the presence Web Service. We assume that these applications belong to a watcher and authenticate to the services in the name of the watcher. identity: represents a user in the real world

NOTE: See Parlay/OSA PAM identities [4], clause 4.4.1.

presence attributes: Contain information about a presentity. An attribute has a name and a value and can be supplied by any device, application or network module that can be associated to the presentity's identity. A watcher can obtains attributes only after he has successfully subscribed to them. Examples for attributes are activity, location type, communication means, and others.

presence information: Consists of a set of attributes that characterize the presentity such as current activity, environment, communication means and contact addresses. Only the system and the presentity have direct access to this information, which may be collected and aggregated from several devices associated to the presentity.

subscription: Before a watcher can access presence data, he has to subscribe to it. One possibility the API provides is an end-to-end subscription concept, in which only identities that have accepted a subscription to their presence can be addressed. Subscriptions can be also automatically handled by server policies edited by the presentity or other authorized users. The service/protocol to manage those policies is out of the scope of the present document.

NOTE: This definition is not related to the term "subscription" in TR 121 905 [1].

watcher and presentity: We use these names to denote the role of the client connected to the presence services.

As in Parlay/OSA PAM [4] the watcher and the presentity have to be associated to identities registered to the system, for example, users, groups of users or organizations.

Abbreviations

For the purposes of the present document, the abbreviations defined in ES 202 391-1 [3] and the following apply:
IETF Internet Engineering Task Force
IMS IP Multimedia Subsystem
ISC IP multimedia subsystem Service Control interface
MMS Multimedia Message Service
PAM Presence and Availability Management
SCF Service Capability Feature
SIMPLE SIP for Instant Messaging and Presence Leveraging Extensions
SIP Session Initiation Protocol
SMS Short Message Service
XCAP XML Configuration Access Protocol
XML eXtensible Markup Language
XMPP eXtensible Messaging and Presence Protocol
XSD XML Schema Definition

Detailed service description

The presence service allows for presence information to be obtained about one or more users and to register presence for the same. It is assumed that the typical client of these interfaces is either a supplier or a consumer of the presence information. An Instant Messaging application is a canonical example of such a client of this interface.

Figure 1 shows the architecture of the Presence Web Service and the underlying services. The Parlay/OSA PAM SCF is the straightforward option and implements the presence server with extended identity, device capability, and presence agent management. Parlay/OSA PAM allows aggregation of presence information from internet, mobile and enterprise users, and others using a presence transport network of SIP or XMPP servers. The Presence Web Service can however communicate directly for example with IMS presence network elements (presence and resource list servers) using the ISC (SIP/SIMPLE) protocol interface.

Figure 1: The Presence web service environment

Relationship to Similar or Supplanted Specifications:

The most important relations are to:
  * Parlay X 2 Terminal Status Web Service [10] and Parlay X 2 Terminal Location Web Service [11]: Both services deal with information that could be considered part of the user's presence information. Communication abilities can be derived from terminal status information, and the user's placetype can be derived from his location.
  * Parlay/OSA PAM [4]: The Parlay/OSA Presence and Availability specification can be considered the big brother of the present document. While Parlay X 2 Presence stays behind Parlay/OSA PAM in terms of flexibility and power - especially concerning attributes and management interfaces - it also extends PAM by introducing end-to-end authorization. The present document aims to be mappable to Parlay/OSA PAM.
  * SIP SIMPLE [5]: The present document aims to be mappable to the SIP/SIMPLE architecture.
  * XMPP (Jabber) (see Bibliography): Many principles of XMPP have been adopted, especially the end-to-end authorization.
  * IETF Rich Presence(see Bibliography). The set of attributes the present document specifies is closely aligned with the IETF's Rich Presence ideas.
  * Group Management [7]: Presence of groups is supported by the present document, however their creation and manipulation has to be done using the Parlay X 2 Address List Management Web Service. In the 3GPP presence context, contact lists and group manipulation is done with the XCAP protocol(see Bibliography).

Namespaces

The PresenceConsumer interface uses the namespace: http://www.csapi.org/wsdl/parlayx/presence/consumer/v2_13

The PresenceNotification interface uses the namespace: http://www.csapi.org/wsdl/parlayx/presence/notification/v2_13

The PresenceSupplier interface uses the namespace: http://www.csapi.org/wsdl/parlayx/presence/supplier/v2_13

The data types are defined in the namespace: http://www.csapi.org/schema/parlayx/presence/v2_13

The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in XML Schema [2]. The use of the name 'xsd' is not semantically significant.

Sequence diagrams

Interface flow overview

The sequence diagram shows the interactions in case both watcher application and presentity are Web Service clients. Compared to the SIP interactions, the subscription notification is separated from the delivery of presence information itself. Based on the subscription result, the watcher can select the polling or notification mode for presence events. Changes in the authorization of presence attributes are propagated to the watchers via the notifySubscription() operation, the blocking of a subscription by the presentity is propagated via a subscriptionEnded operation.

The sequence diagram does not show the internal communication within the presence server. It is assumed that the Presence Consumer and Supplier interfaces are implemented by the same instance. If an implementer of the API find other solutions preferable, he has to take care of the internal communication himself.

Figure 2: Message interaction overview

XML Schema data type definition

Presence attributes are inspired by the IETF's Rich Presence ideas (see Bibliography).

PresenceAttributeType enumeration

The different types of attributes. For each entry in this enumeration there is a separate value type.


Activity The presentity's activity (available, busy, lunch, and others)
Place At what kind of place the presentity is (home, office, and others)
Privacy The amount of privacy the user wants (public, quiet, and others)
Sphere The user's current environment (work, home)
Communication The user's means of communication (phone, mail, and others)
Other A name - value pair for arbitrary presence information

ActivityValue enumeration

This enumeration shows the user's current activity. If the activity is unknown, the attribute value will be ActivityNone, meaning the attribute was not set. If the user is doing something not in this list, the value will be set to ActivityOther.


ActivityNone

Not set.
Available

The user is available for communication.
Busy

The user is busy and is only available for urgent matters.
DoNotDisturb

The user is very busy and does not wish to be disturbed.
OnThePhone

The user is on the phone.
Steering

The user is driving a car / train / airplane, and others
Meeting

The user is in a meeting.
Away

No idea what the user is doing, but he is away.
Meal

The user is eating.
PermanentAbsence

The user is away and will not return for an extended period.
Holiday

The user is on holidays.
Performance

The user is in a theatre / concert.
InTransit

The user is in the transit area of an (air)port.
Travel

The user is travelling.
Sleeping

The user is sleeping.
ActivityOther

The user is doing something not in this list.

PlaceValue enumeration

This enumeration shows the type of the user's current location. If the place type is unknown, the attribute value will be PlaceNone, meaning the attribute was not set. If the user in a place not in this list, the value will be set to PlaceOther.


PlaceNone

Not set.
Home

The user is at home.
Office

The user is in an office.
PublicTransport

The user is on public transport.
Street

Walking on the street.
Outdoors

Generally outdoors.
PublicPlace

The user is in a public place.
Hotel

The user is in a hotel.
Theater

The user is in a theatre or concert.
Restaurant

The user is in a restaurant / bar / and others
School

The user is at school.
Industrial

The user is in an industrial building.
Quiet

The user is in a quiet area.
Noisy

The user is in a noisy area.
Aircraft

The user is on an aircraft.
Ship

The user is on a ship.
Bus

The user is in a bus.
Station

The user is in a bus- or railway station.
Mall

The user is in a mall.
Airport

The user is in an airport.
Train

The user is in a train.
PlaceOther

The user is in a kind of place not listed here.

PrivacyValue enumeration

This enumeration shows the amount of privacy a user currently has. If the privacy is unknown, the attribute value will be PrivacyNone, meaning the attribute was not set. If the privacy is not in this list, the value will be set to PrivacyOther.


PrivacyNone

Not set.
PrivacyPublic

The user is surrounded by other people and cannot discuss openly.
PrivacyPrivate

The user is alone and able to talk openly.
PrivacyQuiet

The user is in a quiet environment and cannot talk at all.
PrivacyOther

None of the other values applies.

SphereValue enumeration

This enumeration shows the sphere within which the user acts. If the sphere is unknown, the attribute value will be SphereNone, meaning the attribute was not set. If the sphere is not in this list (neither work nor home), the value will be set to SphereOther.


SphereNone

Not set.
SphereWork

The user is acting within his work sphere, for example, as a member of his company.
SphereHome

The user is acting within his home sphere, for example, as a private person.
SphereOther

The user is acting neither within his work nor within his home sphere.

CommunicationMeansType enumeration

This enumeration lists communication means. If the communication attribute refers to a means not in this list, it will point to MeansOther.


Phone

The communication attribute refers to a phone (fixed line or mobile or SIP).
Chat

The communication attribute refers to a chat client.
SMS

The communication attribute refers to an SMS client.
Video

The communication attribute refers to a video phone (fixed line or mobile or SIP).
Web

The communication attribute refers to a web client.
EMail

The communication attribute refers to an e-mail client.
MMS

The communication attribute refers to an MMS client.
MeansOther

The communication attribute refers to any other client.

CommunicationMeans structure

This structure describes on way of reaching the presentity.


priority xsd:float

The priority of this communication means. Between 0 and 1, the latter meaning the highest priority.
contact xsd:anyURI

The presentity's contact address for this communication means.


CommunicationMeansType

The type of this communication means.

CommunicationValue structure

This structure describes the various ways of reaching a presentity.


means CommunicationMeans [0..unbounded]

The different ways of reaching the presentity.

OtherValue structure

This structure can be used for storing arbitrary data about a presentity.


Description xsd:string

Description of the content.
value xsd:string

Attribute content.

PresenceAttribute structure

Presence data published by a presentity and retrieved by watchers.


lastChange xsd:dateTime

The time and date when the attribute was changed last.
note xsd:string

An explanatory note..


PresenceAttributeType

Determines the type of the value field.
value One of the six value types; depends on field "type"

The actual value of the attribute.

This data structure is split into two types in the XSD file: A PresenceAttribute contains an AttributeTypeAndValue.

SubscriptionRequest structure

This structure is returned to the presentity by the Presence Web Service and contains the requesting watcher and the attributes he wants to subscribe.


watcher xsd:anyURI

The watcher who wants to gain access to data.
attributes PresenceAttributeType [1..unbounded]

The attributes the watcher wants to see.
application xsd:string

The name of the application running on behalf of the watcher. Note that this field has solely informative purposes, access rights management is based on watcher id only.

PresencePermission structure

The answer from the service to the watcher in the notifySubscription operation.


attribute PresenceAttributeType

The name of the attribute the watcher wanted to subscribe.
decision xsd:boolean

Whether the presentity accepted the subscription. If no, any further fields should be ignored.

Web Service interface definition

This API is separated into three interfaces:
  * PresenceConsumer interface: watcher methods for requesting and subscribing presence data.
  * PresenceNotification interface: is the watcher notification interface for presence events.
  * PresenceSupplier interface: presentity methods for supplying presence data and managing subscriptions.

Fault definitions

ServiceException

SVC0220: No subscription request


messageId

SVC0220.
text

No subscription request from watcher %1 for attribute %2.
variables

%1 - watcher URI.

%2 - type of attribute, from clause 7.1.

SVC0221: Not a watcher


messageId

SVC0221.
text

%1 is not a watcher.
variables

%1 - watcher URI.

Service policies

Service policies for this service.


MaximumNotificationFrequency common:TimeMetric

Maximum rate of notification delivery (also can be considered minimum time between notifications).
MaximumNotificationDuration common:TimeMetric

Maximum amount of time a notification may be set up for.
DefaultNotificationDuration common:TimeMetric

Default amount of time for which a notification will be set up.
MaximumCount xsd:int

Maximum number of notifications that may be requested.
UnlimitedCountAllowed xsd:boolean

Allowed to specify unlimited notification count (for exampled, either by not specifying the optional count part in the startPresenceNotificationRequest message or by specifying a value of zero).
GroupSupport xsd:boolean

Groups may be included with addresses.
NestedGroupSupport xsd:boolean

Are nested groups supported in group definitions.



Copyright © 2003 IBM Corp. All Rights Reserved.