Presence Availability State

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Setting presence states informs the subscribers of the availability status of a user. For example, when the user's computer screen is locked, a Unified Communications Client API application might want to set the user's availability status to indicate that the user is away. If the user does not want to be disturbed, the application needs to set the availability status to Do Not Disturb.

User Availability State Values

A presence state is represented by an integer value. Microsoft Office Communicator defines the availability status with the following integer value ranges. An aggregated state value is calculated by Office Communications Server based on publish user, machine, calendar, and phone states. Because the aggregated state is the product of four variables, an aggregated presence state value range is necessary instead of a single integer value.

Custom Activity States

A custom application can create a set of aggregated state ranges and activity strings and still interoperate with an Office Communicator client. Activity state ranges must fall into the eight general state categories defined in the previous table. Within an individual range, a custom client can define activity values to conform to application requirements. The interoperating Office Communicator client displays the activity status of the custom client using the Office Communicator activity description corresponding to the numeric range of the appropriate activity.

Another instance of the custom client should display the custom activity description defined with the custom activity value. For example, a custom application publishes a custom Available state value of 3105. A remote custom application displays the local user's state as online along with a custom activity string such as Available Using Handheld Device. A user logging on to Office Communications Server using the Office Communicator client also sees the publishing user's state of online including the custom activity string.

Creating Custom Activity States

Creating a custom activity state involves creating a new IUccCategoryInstance interface, casting the interface to the IUccPresenceStateInstance, creating and adding custom activity objects to the interface, and finally publishing the category instance. The category instance is published with an expiration type of UCC_CATEGORY_INSTANCE_EXPIRE_TYPE.UCCCIET_USER. Setting the expiration type to UCC_CATEGORY_INSTANCE_EXPIRE_TYPE.UCCCIET_STATIC requires that an application publish custom activity states for a user only once. A static category does not expire and subsequent executions of the following example code block create duplicate custom activity state categories for the user.

The following C# example creates custom activity states for the general categories of Available, Busy, and Do Not Disturb. The aggregated state ranges defined are the same as the ranges used by an Office Communicator client. Defining ranges in this way ensures that the aggregated state published by a custom client is properly displayed for Office Communicator users.

// create category instance that expires when user logs out
// of client
catStateForUserState = pubMgr.CreatePublishableCategoryInstance(
                          catName,
                          2,          //Container Id
                          0x20000000, //Instance Id
                          UCC_CATEGORY_INSTANCE_EXPIRE_TYPE
                        . UCCCIET_USER,
                          0);
userState = catStateForUserState as IUccPresenceStateInstance;

//add availability string for each type of activity

UccLocaleString custString = null;
UccPresenceActivity pa = userState.CreateActivity();
pa.CreateCustomString("Custom 3000 availability", out custString);
pa.AddCustomString(custString);
pa.SetAvailabilityRange(3000,4499); // this is in the range of online
userState.AddActivity(pa);

custString = null;
pa = userState.CreateActivity();
pa.CreateCustomString("Custom 6000 availability", out custString);
pa.AddCustomString(custString);
pa.SetAvailabilityRange(6000,7499); // this is in the range of Busy
userState.AddActivity(pa);

Publish Custom Availability State Category

The category instances created in the previous example can be published as part of a dedicated publication or added to a publication object containing other categories to be published. Because a publication request is atomic, all categories in the publication fail to publish if one of the categories fails to publish. The following C# example creates a new publication object for the custom availability state categories and publishes them.

// Create a publication and advise for publication events
pub = pubMgr.CreatePublication() as IUccPublication;
UCC_Advise<_IUccPublicationEvent>(pub, this);

// Add the two publishable category instances to the publication
pub.AddPublishableCategoryInstance(catStateForUserState);

//Publish the publication
pub.Publish(null);

See Also

Concepts

Create Contact List Subscription
Add a Contact to the Contact List
Remove a Contact from the Contact List
Granting Permissions to View Published Presence States
Presence Availability State
Sample Contact Presence Handling Class
Category and Category Instances
Publication and Subscription Objects