LocalOwnerPresence

Article
01/20/2015

The LocalOwnerPresence class has members that a presentity can use to publish its presence information to Microsoft Lync Server 2010.

Presence Publication

The LocalOwnerPresence property on the endpoint can be used to manage the presence information of the endpoint owner (also known as the local presentity). Presence information consists of units of presence information called categories that can be assigned to various Access Control Lists (ACLs) that are referred to as containers. These containers provide a way for the local presentity to control access to the presentity’s presence information. For more information, see “Relationship Level Management” later in this topic.

Categories, identified by type, represent objects that can be published or deleted. The well-known categories that are recognized by Microsoft Lync Server 2010, have schematic representations. If an application is intended to use a customized category, the category name must be configured at the server's end. Otherwise publication of such a category will be rejected by the server.

Microsoft Unified Communications Managed API (UCMA) 3.0 provides strongly typed definitions for some commonly used presence categories, such as ContactCard, PresenceState, Services, and Note. These classes have a common base class, the PresenceCategory class. Applications can extend this base class to define custom categories and publish them using the UCMA 3.0 described here. If a developer wishes to use a simplified model to publish a category that is represented by a name and a string representation of the content XML, the CustomPresenceCategory class is a simpler alternative.

Category publication involves providing the category data together with the container and instances IDs that identify where the category data are to be published. Applications that use user endpoints are strongly encouraged to take advantage of the Manifest-based publication model. Application endpoints represent an advanced publication scenario and are required to provide these details.

Category publication also involves version management, which is internally managed by UCMA 3.0.

Manifest-Based Publication for UserEndpoint

It is recommended that the following simplified asynchronous methods be used for user endpoints so that a consistent behavior is achieved when interoperating with Lync so that they can remain agnostic to container ID and instance ID details.

The application can publish a collection of presence categories as a batch process using the aforementioned methods. UCMA 3.0 ensures that the presence categories will be published to the proper containers, providing instance IDs where relevant. It is to be noted that they have to be subscribed to LocalOwnerPresence in order to use these methods. Any exception during the publication of an individual category in the list will result in the failure of the entire batch.

Applications must provide the instance IDs for custom categories and the ContactCard category. For others, UCMA 3.0 automatically supplies them.

UCMA 3.0 and Lync endpoints drive their publication behavior based on a common non-configurable manifest that is defined by the administrator in the enterprise. This manifest specifies publication rules for well-known categories recognized by Lync Server 2010. If an application attempts to publish an unrecognized category using the BeginPublishPresence method, an InvalidOperationException is thrown. All publications using this method are queued and completed in a serial fashion.

The corresponding methods to delete the published categories are the BeginDeletePresence(ICollection<PresenceCategory>, AsyncCallback, Object) and EndDeletePresence(IAsyncResult) methods.

Presence Publication for ApplicationEndpoint and Advanced Publication Scenarios for UserEndpoint

For advanced usage scenarios, use the BeginPublishPresence(ICollection<PresenceCategoryWithMetaData>, AsyncCallback, Object) and EndPublishPresence(IAsyncResult) methods.

The PresenceCategoryWithMetaData class encapsulates the PresenceCategory being published, together with other publishing details such as container ID, instance ID, version, and expiry type. It is expected that an advanced user will understand the impact of his publication and can manage relationship levels (watcher list).

For application endpoints that are intended to persist their presence information; that is, that rarely change their presence information, developers can take advantage of the simplified presence publication mechanism that UCMA 3.0 offers. For more information, see “Publishing Presence for an ApplicationEndpoint” later in this topic.

To delete the published categories, use the BeginDeletePresence(ICollection<PresenceCategoryWithMetaData>, AsyncCallback, Object) and EndDeletePresence(IAsyncResult) methods.

Presence Categories provided by UCMA 3.0

ContactCard

The ContactCard class represents the "contactCard" category. This category represents a variety of contact information about the user represented by the endpoint.

PresenceState

The PresenceState class represents the "state" category. This category represents the availability of the endpoint owner and how "reachable" they are for communications. The different types of the state category represented by PresenceStateType are shown in the following table.

State category type	Description
AggregateState	The overall availability of the endpoint owner.
EndpointState	The availability of the endpoint owner from this particular endpoint.
UserState	The availability preference of the endpoint owner.
PhoneState	Whether and how the endpoint owner is using a phone.
CalendarState	The availability of the endpoint owner based on their calendar data.

The availability value of a presentity is represented by a long integer, in which smaller values indicate higher availability. There are many static helper methods on the PresenceState class that can be used to publish well-known availability values.

Typically, only endpoint, user, phone, and calendar states are published by enterprise endpoints, thereby allowing the server to combine them using certain rules into one final aggregated value.

UCMA 3.0 does not allow instantiating and publishing a CalendarState category.

Note

The Note class represents the "note" category. A note category contains a message that watchers can view. There are two types of note: personal and out-of-office. UCMA 3.0 provides methods to configure and publish both types of notes.
Services

The Services class represents the "services" category, which represents the cumulative service capabilities of a presentity. When endpoints publish a "device" category that represents the capabilities of the device (such as support for audio, video, and text), the server aggregates these capabilities into a single services category that can be consumed by watchers as well as the endpoint owner.

UCMA 3.0 does not recommend direct publication of the services category for user endpoints. Application endpoints can publish the services category directly, given that there is usually only a single instance of the application endpoint contact object.
CustomPresenceCategory

If a UCMA 3.0 application is intended to publish a custom category or a well-known category for which the API does not have a strongly-typed implementation, the application can do so by instantiating a CustomPresenceCategory with the name and a string representing the XML content. Optionally, an instance ID can be supplied. Otherwise, the value is automatically determined, provided that it is a well-known category in the Lync Server 2010 subsystem (defined in the server manifest).

Presence Subscription and Notification Handling

A local presentity who wishes to know its current presence data and be informed of any changes to this data can do so by subscribing to its own presence information. This can be done by calling the BeginSubscribe(AsyncCallback, Object) and EndSubscribe(IAsyncResult) methods.

The following table shows the events on the LocalOwnerPresence class and the name of the presence data obtained from them.

Event	Presence data obtained from event
ContainerNotificationReceived	Access control lists lilsting member URIs and domains.
DelegateNotificationReceived	List of delegates of the endpoint owner.
PresenceNotificationReceived	Details on presence categories and the containers to which they are published.
SubscriberNotificationReceived	List of watchers (subscribers).

Category Notification Parsing

For UserEndpoint instances, key publishing APIs cannot be used unless the object referred to by the LocalOwnerPresence property is in the Subscribed state. For ApplicationEndpoint instances, it is recommended, but not required, that LocalOwnerPresence be in the Subscribed state.

The list of presence categories returned by the AllCategories property on the LocalPresentityNotificationEventArgs object can be extensive. For this reason, Lync Server 2010 filters this list to a smaller representative list that highlights categories published to the local owner’s self container. For user objects this is a different container for different categories representing the container that is most representative of that category. For contact objects, the list includes all categories in the container 0.

Lync Server 2010 further pre-parses this information and populates the common categories on the LocalPresentityNotificationEventArgs object, including those in the following list.

ContactCard

Separate ContactCard instances are aggregated to produce a single instance for easy consumption.
AggregatedPresenceState
EndpointPresenceState
UserPresenceState
ServiceCapabilities
OutOfOfficeNote
PersonalNote

Container Notification Parsing

Container notifications represent the Access Control Lists of the endpoint owner and are indexed by the container ID. These ACLs represent individual member URIs, specific domain URIs and broad domain URIs such as watchers in the enterprise, public cloud. or federated. This data can be used to control which presence data of the endpoint owner watchers are allowed to see. For more information, see “Relationship Level Management”, later in this topic.

Subscriber Notification Parsing

Subscribers represent details of the watchers subscribed to the endpoint owner's data.

Delegates Notification Parsing

This notification gives information of the delegates of the endpoint owner (delegator) and also whether they can publish or assign other delegatees on their behalf.

Relationship Level Management

Presentities in a Lync subsystem can control access to their presence data by doing relationship management. This involves assigning subscribers or watchers to various Access Control Lists (ACLs) or containers limiting their viewership to the presence data in those containers.

Entries in an ACL can be:

Specific URIs of watchers.
Specific domains names, such as contoso.com or hotmail.com.
SourceNetwork flags indicating broad domains such as users in the same enterprise, users on Lync Server 2010 servers that are federated with this enterprise, users in the public cloud, or everyone.

The BeginUpdateContainerMembership(ICollection<ContainerUpdateOperation>, AsyncCallback, Object) and EndUpdateContainerMembership(IAsyncResult) methods on a LocalOwnerPresence object can be used to assign watchers to the various containers.

Applications can register to receive container notifications when the ContainerNotificationReceived event is raised.

Relationship Level

A relationship level between a presentity and a watcher is defined as the highest container that the presentity has assigned the watcher to. Lync assigns a specific relationship name to certain well defined containers. UCMA 3.0 defines the relationship levels in the PresenceRelationshipLevel enumeration.

Relationship level	Container ID	Description
Blocked	32000	Contact is blocked.
Personal	400	Contact is personal (friends and family).
Workgroup	300	Contact belongs to the same workgroup or team.
Colleagues	200	Contact belongs to the same company.
External Contact	100	Contact is external.
Everyone	0	No specific relationship level was found for the contact. This is the default relationship level

To determine the relationship of the watcher to the local owner (or endpoint owner), call the GetPresenceRelationshipLevel(RealTimeAddress, SourceNetwork) method. This method can be accessed through the PresenceServices property on a UserEndpoint instance.

Relationship Level Determination

Because a subscriber can be present in multiple containers owned by a publisher, the following steps can be used to determine the relationship level (container). Lync Server 2010 determines a subscriber’s container for a particular category request using a similar algorithm.

Find the container with the highest container ID in which the subscriber’s URI is explicitly listed. If one such container is found, end the search.
Find the container with the highest container ID in which the subscriber’s domain is listed in any of its domain membership lists. If one such container is found, end the search.
If the subscriber is in the same enterprise as the publisher, choose the container with the highest container ID that has the same-enterprise bit set. If one such container is found, end the search.
If the subscriber is a federated user, select the container with the highest container ID that has its federated-user flag set. If one such container is found, end the search.
If the subscriber is a public-cloud user, select the container with the highest container ID that has its public-cloud-user flag set. If one such container is found, end the search.
If the default container contains the category, select that container.

Bootstrapping

When a user is provisioned on Lync Server 2010, there are no ACLs in any of the containers except container 0, the container that allows access by every presentity (SourceNetwork.Everyone). Users who take advantage of presence services in UCMA 3.0 or those logged into Microsoft Lync 2010 are “bootstrapped,” which means that some containers are automatically assigned certain memberships as dictated by the server manifest. For example, in Lync Server 2010, users not operating in Private mode have members of their enterprise automatically assigned to the Colleagues (200) container, and members of federated networks are assigned to their Public (100) container.

Lync Server 2010 relationship management APIs are designed under the assumption that relationship management is primarily of importance to UserEndpoint objects. Bootstrapping is not done for ApplicationEndpoint instances, as this endpoint type is usually intended to have its presence information available to all. It is for this reason that application endpoints publish data directly into container 0.

Managing Watchers

A watcher (also known as a subscriber) is an entity that receives presence information published by another presentity. When one user subscribes to another user's presence by assigning a non-null value to the SubscriptionContext property on the RemotePresentitySubscriptionTarget object with the intention of building a contact relationship with the publishing user, the server notifies the publishing user of the subscription request.

After the publishing user is notified with the subscription request, the publisher is expected to acknowledge the request to the server so that the server can remove the entry that caused the notification to occur. This is an opportunity for the publishing user to find out who is subscribing to the information being published, and to place the subscribing user into the appropriate access control list (ACL) using the update operations in the ContainerUpdateOperation class, if necessary.

The notified user acknowledges the request by calling the BeginAcknowledgeSubscriber(String, AsyncCallback, Object) method.

An endpoint can register for watcher notifications by registering a handler for the SubscriberNotificationReceived event on a LocalOwnerPresence instance. The SubscriberNotificationEventArgs class, which is associated with this event, has a WatcherList property that lists all watchers who have subscribed to the application’s presence information.

Watcher notifications and acknowledgement is not a gatekeeping mechanism, in that the watcher who requests information does not require permissions before doing so. However, a user can assign memberships to the watcher, thereby controlling the amount of data being shared.