|
|
The RESTful Presence interfaces allow an application to act as either of two different parties to a presence interaction: as a presentity or as a watcher. A presentity agrees to have certain data (called attributes) such as current activity, available communication means, and contact addresses made available to others while a watcher is a consumer of such information. As a watcher, an application can request to subscribe to all or a subset of a presentity’s data, poll for that data, and start and end presence notifications. As a presentity, an application can publish presence data about itself, check to see if any new watchers wish to subscribe to its presence data, authorize those watchers it chooses to authorize, block those it wishes not to have access, and get a list of currently subscribed watchers.
In the listings below, bold indicates a required attribute, <> a descriptive comment.
| Note: | An HTML version of this information is at http://host:port/rest/presence/index.html where host and port depend on the Oracle Communications Services Gatekeeper installation. |
Polls for any watchers who want to subscribe to this presentity’s data.
http://host:port/rest/presence/subscriptions?status=open
"application": "String",<A descriptive name for the application that operates on behalf of the watcher. Information only>
"attributes": ["Activity|Place|Privacy|Sphere|Communication|Other"],<The attributes this watcher wishes to see. An empty array means all attributes. See Table 10-1 for more information.>
"watcher": "URI"<The address of the watcher whose request this is>
Gets an array of current watchers
http://host:port/rest/presence/subscriptions?filter=watcher
The addresses of the current watchers
Used to add watchers who have recently asked for subscriptions or to change permissions for any current watchers.
http://host:port/rest/presence/subscription/authorization
"decision": "Boolean",<Whether to allow the watcher>
"presenceAttribute": "Activity|Place|Privacy|Sphere|Communication|Other"
}],<The attributes this watcher wishes to see. An empty array means all attributes. See Table 10-1 for more information.>
"watcher": "URI"<The watcher whose request is being evaluated>
Requests to subscribe to a presentity’s data. No data will be available until the presentity authorizes the watcher using Update Subscription Authorization.
http://host:port/rest/presence/subscription
"application": "String",<A descriptive name for the application whose data the watcher wishes to access. Informational only>
"presentity": "URI",<The address of the presentity or group whose data is being requested>
"correlator": "String",<A correlator identifying this request>
"endpoint": "URI",<The endpoint address to which the Notfiy Subscription notification is delivered>
"interfaceName": "String" <Descriptive only>
"attributes": ["Activity|Place|Privacy|Sphere|Communication|Other"]<The attributes this watcher wishes to see. An empty array means all attributes. See Table 10-1 for more information.>
Allows a presentity to block a watcher’s access to the presentity’s data. The watcher is notified with a Subscription Ended notification.
http://host:port/rest/presence/subscription/${watcher}
${watcher}: The URI of the watcher to block
Begin delivering presence data to the endpoint defined in the reference attribute. This operation is only functional if the presentity has approved the watcher.
http://host:port/rest/presence/notification
"checkImmediate": "Boolean",<Whether to check immediately after establishing the notification>
"frequency": {<Maximum frequency of notifications (can also be considered minimum time between notifications). In the case of a group subscription the service must make sure this frequency is not violated by notifications for various members of the group, especially in combination with checkImmediate.>
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",<The metric in which to measure the frequency>
"units": "Integer"<The number of units of the metric>
"presentity": "URI",<The presentity or group whose data is being accessed>
"correlator": "String",<A correlator identifying this notification>
"endpoint": "URI",<The endpoint address to which the notification is to be delivered>
"interfaceName": "String" <Descriptive only, the type of notification>
"attributes": ["Activity|Place|Privacy|Sphere|Communication|Other"],<The attributes this watcher wishes to see. An empty array means all attributes. See Table 10-1 for more information.>
"count": "Integer",<The maximum number of notifications. Zero or unspecified means no maximum>
"duration": {<The length of time over which notifications occur. For service default, do not specify>
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",<The metric in which to measure the duration>
"units": "Integer"<The number of units of the metric>
The presentities to whose attributes the watcher did not successfully subscribe. Empty if there were no issues.
http://host:port/rest/presence/notifications
The URI of the pub/sub server.
http://host:port/rest/presence/notification/${correlator}
The correlator passed in when the notification was started.
Gets the aggregated presence data of a presentity to whose data the watcher has previously successfully subscribed. Only the attributes that the watcher is authorized to see are returned.
http://host:port;rest/presence/data?query=${query}
"presentity": "URI",<The address of the presentity being requested>
"attributes": ["Activity|Place|Privacy|Sphere|Communication|Other"] <The attributes being requested.An empty array means all attributes. See Table 10-1 for more information.>
"lastChange": "Calendar",<The time and date the data last changed in ISO 8601 extended format >
"typeAndValue": {<The presence information>
"unionElement": "Activity|Place|Privacy|Sphere|Communication|Other",<See Table 10-1. Determines what data is presented.>
"activity": "ActivityNone|Available|Busy|DoNotDisturb|OnThePhone|Steering|Meeting|Away|Meal|PermanentAbsence|Holiday|Performance|InTransit|Travel|Sleeping|ActivityOther",<What the presentity is doing. ActivityNone indicates the value has not been set. ActivityOther refers to any non-listed activity type.>
"communication": {"means": [{<Connection information for presentity’s preferred forms of communication>
"contact": "URI",<The contact address for this particular means>
"priority": "Float",<The priority of this particular means. Between 0 and 1, with 1 indicating most preferred means>
"type": "Phone|Chat|Sms|Video|Web|Email|Mms|MeansOther"<The type of contact client for this particular means. Video refers to a video phone. MeansOther refers to any other client type>
"other": {<An arbitrary name/value pair for the Other element of Table 10-1>
"place": "PlaceNone|Home|Office|PublicTransport|Street|Outdoors|PublicPlace|Hotel|Theatre|Restaurant|School|Industrial|Quiet|Noisy|Aircraft|Ship|Bus|Station|Mall|Airport|Train|PlaceOther",<The type of location for the presentity. PlaceNone means no value has been set. PlaceOther refers to any other type of place.>
"privacy": "PrivacyNone|PrivacyPublic|PrivacyPrivate|PrivacyQuiet|PrivacyOther",<The level of privacy in the presentity’s current environment. PrivacyNone means the value has not been set. PrivacyOther refers to any other privacy level>
"sphere": "SphereNone|SphereWork|SphereHome|SphereOther"<The sphere within which the presentity is currently acting. SphereNone means the value has not been set. SphereOther refers to any other sphere.
"note": "String"<An explanatory note>
Allows the presentity to publish presence information
http://host:port/rest/presence/data
"lastChange": "Calendar",<The time and date the data last changed in ISO 8601 extended format >
"typeAndValue": {<The presence information>
"unionElement": "Activity|Place|Privacy|Sphere|Communication|Other",<See Table 10-1. Determines what data is presented.>
"activity": "ActivityNone|Available|Busy|DoNotDisturb|OnThePhone|Steering|Meeting|Away|Meal|PermanentAbsence|Holiday|Performance|InTransit|Travel|Sleeping|ActivityOther",<What the presentity is doing. ActivityNone indicates the value has not been set. ActivityOther refers to any non-listed activity type.>
"communication": {"means": [{<Connection information for presentity’s preferred forms of communication>
"contact": "URI",<The contact address for this particular means>
"priority": "Float",<The priority of this particular means. Between 0 and 1, with 1 indicating most preferred means>
"type": "Phone|Chat|Sms|Video|Web|Email|Mms|MeansOther"<The type of contact client for this particular means. Video refers to a video phone. MeansOther refers to any other client type>
"other": {<An arbitrary name/value pair for the Other element of Table 10-1>
"place": "PlaceNone|Home|Office|PublicTransport|Street|Outdoors|PublicPlace|Hotel|Theatre|Restaurant|School|Industrial|Quiet|Noisy|Aircraft|Ship|Bus|Station|Mall|Airport|Train|PlaceOther",<The type of location for the presentity. PlaceNone means no value has been set. PlaceOther refers to any other type of place.>
"privacy": "PrivacyNone|PrivacyPublic|PrivacyPrivate|PrivacyQuiet|PrivacyOther",<The level of privacy in the presentity’s current environment. PrivacyNone means the value has not been set. PrivacyOther refers to any other privacy level>
"sphere": "SphereNone|SphereWork|SphereHome|SphereOther"<The sphere within which the presentity is currently acting. SphereNone means the value has not been set. SphereOther refers to any other sphere.
"note": "String"<An explanatory note>
The content of notifications delivered to the designated endpoint.
"lastChange": "Calendar",<The time and date the data last changed in ISO 8601 extended format >
"typeAndValue": {<The presence information>
"unionElement": "Activity|Place|Privacy|Sphere|Communication|Other",<See Table 10-1. Determines what data is presented.>
"activity": "ActivityNone|Available|Busy|DoNotDisturb|OnThePhone|Steering|Meeting|Away|Meal|PermanentAbsence|Holiday|Performance|InTransit|Travel|Sleeping|ActivityOther",<What the presentity is doing. ActivityNone indicates the value has not been set. ActivityOther refers to any non-listed activity type.>
"communication": {"means": [{<Connection information for presentity’s preferred forms of communication>
"contact": "URI",<The contact address for this particular means>
"priority": "Float",<The priority of this particular means. Between 0 and 1, with 1 indicating most preferred means>
"type": "Phone|Chat|Sms|Video|Web|Email|Mms|MeansOther"<The type of contact client for this particular means. Video refers to a video phone. MeansOther refers to any other client type>
"other": {<An arbitrary name/value pair for the Other element of Table 10-1>
"place": "PlaceNone|Home|Office|PublicTransport|Street|Outdoors|PublicPlace|Hotel|Theatre|Restaurant|School|Industrial|Quiet|Noisy|Aircraft|Ship|Bus|Station|Mall|Airport|Train|PlaceOther",<The type of location for the presentity. PlaceNone means no value has been set. PlaceOther refers to any other type of place.>
"privacy": "PrivacyNone|PrivacyPublic|PrivacyPrivate|PrivacyQuiet|PrivacyOther",<The level of privacy in the presentity’s current environment. PrivacyNone means the value has not been set. PrivacyOther refers to any other privacy level>
"sphere": "SphereNone|SphereWork|SphereHome|SphereOther"<The sphere within which the presentity is currently acting. SphereNone means the value has not been set. SphereOther refers to any other sphere.
"note": "String"<An explanatory note>
"correlator": "String",<The correlator passed in with the notification set up>
"presentity": "URI"<The presentity whose data this is>
"presentity": "URI",<The address of the presentity who has or has not authorized the watcher to whom this notification is sent>
"decision": "Boolean",<Whether the subscription is authorized>
"presenceAttribute": "Activity|Place|Privacy|Sphere|Communication|Other"
}]<What attributes are authorized. See Table 10-1>
{"statusEnd": {"correlator": "String"}}
The notification indicated by the correlator has ended, because either the duration or count was completed. This is not delivered in the case of an error or the use of End Presence Notification.
"presentity": "URI",<The presentity in question>
"reason": "String"<Timeout or blocked>
The subscription has been terminated, either blocked by the presentity or because of a timeout or connection failure.
The content of possible error messages.
"type":"org.csapi.schema.parlayx.common.v2_1.ServiceException"
"type":"org.csapi.schema.parlayx.common.v2_1.PolicyException"
|