The Unified Communications Managed API 2.0 Core SDK enables the user to specify permissions so that different groups of people can have access to different sets of presence information based on their access level. The UCMA 2.0 Core SDK also employs a user's presence state, such as "Do Not Disturb," and the permission level provided to the caller, to make call-handling decisions such as automatic rejection and call routing.

In UCMA 2.0 Core SDK an endpoint owner (a local owner presentity) can publish presence information and other users (remote presentities) can subscribe to some of that presence information.

Note:
Although a remote user can see all of the containers that a presentity publishes, the remote user can subscribe only to the state, services, calendarData, note, and contactCardcategories.

The LocalOwnerPresenceproperty on an endpoint provides access to a LocalOwnerPresenceinstance, whose members can be used to carry out such tasks as publishing presence, updating container membership, subscribing for delegate notification, and acknowledging subscription requests from remote presentities.

In a complementary way, the RemotePresenceproperty on an endpoint provides access to a RemotePresenceinstance, whose members can be used for such purposes as specifying the presentities from which to subscribe or unsubscribe.

An application that is not intended to receive all of the presence information published by other presentities can supply a filter to the endpoint to restrict the presence types in the subscription by using the PresenceSubscriptionCategoriesproperty on a RemotePresenceinstance. Subscription is persistant, so it is sometimes more efficient to query a remote user for presence information when it is needed, such as for showing the presence of a user in a search pane. An endpoint supports this capability by exposing the BeginPresenceQuerymethod by way of the endpoint’s RemotePresenceproperty.

Presence containers are access control list (ACL) buckets that are made available to a user to limit the information being shown to subscribers, which are also known as watchers. A presence container is identified by a number, its container ID. This container, which is created when it is needed, holds data and a list of the members of that container. Typically, a client defines a set of containers for a specific purpose. For example, the Microsoft Office Communicator client defines a list of predefined containers, each with a specific purpose. One container is defined for users from the same company (ID = 200), another container is defined for users from the public Internet cloud (PIC) (ID = 100), and a third container is defined for blocked users (ID =32000). Each container can specify its members by explicitly listing their SIP URIs or SIP domains, or by specifying flags that indicate whether the members are in the same company, are in the public cloud, or are federated users. The following table shows some of the predefined containers in Microsoft Office Communicator. For more information, see [MS-PRES]: Presence Protocol Specification .

An application can publish a specific presence object into one or more containers. When users subscribe to the presence of another user, the server (Office Communications Server) determines the presence items that will be given to the users based on the publisher's ACL setting for the subscribers and the presence items currently published. All members in a given container can see any data that is published to that container.

The data in a presence instance is represented as categories. A publisher presentity publishes categories, and a subscriber can subscribe to one or more of the following categories: note, contactCard, calendarData, services, and state.

Each presence category item contains a variety of metadata about the presence item as well as the actual data for the item. For example, it can specify the container ID to which it is published, the expiry policy, the name of the item, the publication time, and other information. Determining the correct container into which to publish presence data can be challenging. UCMA 2.0 Core SDK simplifies this process by incorporating a publication grammar (available only to UserEndpointinstances) that is similar to the mechanism used by Office Communicator to publish presence. An application can define additional custom presence categories, although publishing them requires the administrator to configure the server to allow new presence categories.

UCMA 2.0 Core SDK offers presence publication on the UserEndpoint(for human users) and ApplicationEndpoint(for applications and services) classes. The LocalOwnerPresenceproperty on each of these classes provides access to a LocalOwnerPresenceinstance, which has two overloaded BeginPublishPresencemethods. UserEndpointcan publish presence in either of two ways: by calling the BeginPublishPresencemethod to publish a publication grammar (and passing a collection of PresenceCategoryinstances in the call), or by calling the other BeginPublishPresencemethod to explicitly specify the category metadata and to publish the category item directly to a container (and passing a collection of PresenceCategoryWithMetadatainstances). The declarations for these methods are shown in the following example.

	Copy Code
public IAsyncResult BeginPublishPresence(ICollection<PresenceCategory> categoryItems, AsyncCallback userCallback, object state); public IAsyncResult BeginPublishPresence(ICollection<PresenceCategoryWithMetadata> categories, AsyncCallback userCallback, object state);

Aggregation is necessary so that multiple clients, devices, endpoints, or services, all publishing on behalf of the same user, can arrive at a single value for an arbitrary publishing category. These different publishing clients of the user are generally not aware of one another nor are they aware of the data published by each other.

For example, a service might publish a user’s calendar, while a device being used by a user might publish its activity. Both of these publications affect the overall presence “status” of the user, but neither the service nor the device has all of the information needed to publish the user’s overall status. The implication is that another processing entity, with access to both pieces of information, and the knowledge of how to combine them, must exist to produce the overall status. This other processing entity is the Office Communications Server computer.

Note:
Some processing of presence data, “aggregation,” occurs at the client level. For example, aggregation of contactCarddata occurs on each client. Device ( service) and stateaggregation is carried out on the server.

Office Communications Server aggregates presence state publication and device capabilities publications for one or more UserEndpointinstances owned by a user. The server evaluates multiple UserEndpointstate publications and creates a single, summarized aggregate state for the well-known containers. The server also aggregates the various device capabilities published by multiple UserEndpointinstances and summarizes the user’s device capabilities into a services category that describes the modalities (such as IM, audio, and video) on which a user is available to communicate.

“Aggregate Availability” is a nonnegative number that designates how “reachable” a contact is. Some standard values that Office Communicator client publishes are shown in the following table.

The following illustration shows how presence information from a variety of devices is aggregated and published. It also shows the mechanism by which a remote user can subscribe to that presence information.

Publishing presence, aggregating presence, and subscribing to presence