Category Instances

Article
06/14/2014

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.

A category instance defines a particular data item of a given type. In Unified Communications Client API, a category instance is encapsulated by the IUccCategoryInstance interface.

Category Instance Properties

The category instance interface exposes a set of properties whose purpose is to provide access to such attributes as the publishing user, instance, version, expiration type and time, version, and category context. A generic category instance created and published by an application must use the Value property to publish and receive application-specific data. The Value property must be an XML-formatted string. When a category instance is cast to a specific instance such as IUccContact, the value property is null.

Instance ID

A category instance is identified by an instance ID (a number) and the specified category name. This identification scheme allows a publisher to publish the same category of data multiple times. For example, a user might want to publish the state category from two different endpoints: a laptop and a desktop computer. The two category instance must be considered distinct. The desktop computer might show the user is away when the user is online using the laptop computer. In this case, different instance ID values help to distinguish the two instances of the state category. Three properties of a category instance are considered key values. When taken together, Name, InstanceId, and ContainerId provide an unique identifier for a given category instance.

Instance ID is exposed by the InstanceId property.

Version Number

Each category instance has a version number. The value is assigned by the server. The version number allows multiple clients to publish the same category instance and synchronize the data among themselves. The semantics of the version number follow the InterlockedCompareExchange function semantics: the publication is updated only if the publisher presents the current version number. The server automatically increments the version number when it updates the data.

The version number is exposed by the Version property.

Category Expiration

Unified Communications Client API supports several ways in which a category instance can expire. For a complete collection of expiration types, see UCC_CATEGORY_INSTANCE_EXPIRE_TYPE.

A Unified Communications Client API client can set a category instance to expire:

When the user logs off the server from all the endpoints.
When the user logs off the server from the endpoint in which the category instance is published.
When a specified time period is reached. Each category instance can have a client-specified expiration time in seconds. When the published data is updated, the expiration time is updated with the new value provided by the client. If the published category instance is never subsequently updated, the server deletes it after the time elapses beyond the expiration time since the last publication. Expiration time is exposed by the ExpiryTime property.

Note

The client can also set the instance to never expire. A category that does not expire is a static category. Use the UCC_CATEGORY_INSTANCE_EXPIRE_TYPE.UCCCEIT_STATIC enumeration for this type of expiration.

The expiry type is defined in UCC_CATEGORY_INSTANCE_EXPIRE_TYPE enumeration.

Last Published Time

The server maintains the last publication time for each category instance and makes this available in subsequent notifications of the update of a category instance. Subscribers can use this metadata in some situations to resolve any ambiguities over whether to accept a notification of a change relative to what data they already have for the category instance. The granularity of last publish time is only to the minute. That is, it is not possible to distinguish between two updates to the same item within a minute based on last publish time alone.

The last published time is exposed by the PublishedTime property.

Category Context

The category context property returns an IUccCategoryContext interface. This interface represents the category type to which an instance belongs. For example, an IUccCategoryInstance that is cast to the IUccContact interface is an instance of the contacts category type. In this case, the category context property returns a category context whose Name property returns the string "contacts".

The category context property of a category instance provides a presentity property that identifies the publisher of the category data.

Container Id

The container Id property of a category instance identifies the ACL container from which the category is published. The container Id property is only filled for category instances who are members of the categories context. The categories context is a collection of categories published by the local user. Category instances received in a subscription to a remote user do not contain Container Id or Container property values.

Is Published by Local Endpoint

This Boolean property indicates the publishing origin of the category instance. Self-published category instances return a True value, while category instances received in a subscription to a watched user always return a False value.

Presentity

This property returns an IUccPresentity object representing the publisher of the category instance.

Publication Operation

The publication operation property is a write-only property. It is set in the process of the publication of a category instance. The values can be UCC_PUBLICATION_OPERATION_TYPE.UCCPOT_ADD and UCC_PUBLICATION_OPERATION_TYPE.UCCPOT_REMOVE. The property must be set prior to calling the Publish method on a publication object.

Value

This property is usually null. The property can be filled when publishing and subscribing to generic categories. Office Communications Server itself publishes such generic categories as categories and legacyInterop. In these cases, the Value property contains data. The returned value of the Value property is an XML string. The XML string must be well-formed. The custom client is responsible for validating the XML string against an application schema.

Category Instance Creation

A Unified Communications Client API client creates a category instance for publication by calling the CreatePublishableCategoryInstance method. The method requires the input of the category name (see Category) and the information discussed previously, as well as the container ID, which is discussed in Category Publication.