Programming Patterns with Category Instances
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.
Creating a Generic Category Instance
An application creates a generic category instance by calling the CreatePublishableCategoryInstance method. The client must provide a category name, container ID to publish to, instance ID, and expiration type.
Note
The custom category name must be registered on the Office Communications Server computer by a server administrator.
- Declare the following types to be passed as arguments to CreatePublishableCategoryInstance:
- string, which represents the category name you publish.
- int, which is the container ID of the ACL container to which the category will be published.
- int, which is the instance ID used to give the new category a unique identifier.
- UCC_CATEGORY_INSTANCE_EXPIRE_TYPE. This is the enumeration to define the expiration type of the category.
- int, which is the expiration time if the expiration type is not UCC_CATEGORY_INSTANCE_EXPIRE_TYPE.UCCCIET_STATIC.
The following C# example creates a custom category to hold GPS location data for the publishing user.
// Create a publishable category instance for "GPSData" category to
// publish the user GPS location.
string catName = "GPSData"
catStateForUserState = pubMgr.CreatePublishableCategoryInstance(
catName,
2,
0x20000000,
UCC_CATEGORY_INSTANCE_EXPIRE_TYPE
.UCCCIET_USER,
0);
Using an IUccPublicationManager type, call CreatePublishableCategoryInstance.
Assign a value to the new category. Fill the read/write property Value with an XML-formatted string.
Creating a Typed Category Instance
An application creates a typed category instance (for example, a state category instance) by calling the CreatePublishableCategoryInstance method. The returned IUccCategoryInstance interface is cast to the appropriate type-specific category instance (for example, an IUccPresenceStateInstance). Calling CreatePublishableCategoryInstance on the publication manager creates a new category instance to be published. Another way to create a publishable category instance is to call CreatePublishableCategoryInstance on an existing category instance. You do this when you want to publish an update to a category that has been previously published and returned in a subscription. Using this method, you are cloning an existing published category, updating the clone, and publishing it as a replacement for the original category.
The programming pattern to create a typed category instance is the same as the pattern used to create a generic category with one exception: Using a well-known Unified Communications category name in the first parameter position of the method creates a category instance that can be cast to one of the Unified Communications client strongly typed category instances.
For example, the following example creates for publication a state category instance in container 2. The category instance expires if it remains intact longer than the specified expiration time of 100 seconds.
Follow the programming pattern described for creating a generic category instance with three exceptions:
- Assign a category name from the set of well-known category names. For example, set the category name to state to publish user or machine state.
- Cast the IUccCategoryInstance object created to the specific category interface to be published. To continue the previous example, cast IUccCategoryInstance to IUccPresenceStateInstance.
- Assign a value to the category using the new strongly typed category instance interface. In this example, set the Availability property of the state category to an integer value in the range of acceptable user state availability values.
Receiving Notifications of a Category Instance
In a subscription session, after a subscribed publisher creates and adds a category instance to a publication, the subscribing client receives the newly published category instance if it registers for and handles the OnCategoryInstanceAdded event. If the category context name is one of the Unified Communications well-known category names, the received category instance should be cast to the appropriate strongly typed category instances. In the following example, the common category state is received. The code performs a cast of the IUccCategoryInstance to IUccPresenceStateInstance.
- Subscribe to the contacts category to receive local user's contact list.
- For each contact received in the contacts subscription, advise for presentity events.
- Handle the OnCategoryContextAdded event raised by the presentity object. In the callback function, advise for category instance events whose context is received in the callback function event data argument.
- Handle OnCategoryInstanceAdded events raised when a category instance is added to the advised category context.
- Determine the context of the new category instance by reading the name property of the category context property of the event source argument.
- Cast the generic IUccCategoryInstance object to the type-specific category.
- Get the interested values from the exposed properties of the new interface. If the category context name is not in the set of well-known categories, the category instance is not to be cast to a strongly typed interface. Instead, read the Value property directly from the IUccCategoryInstance object.
The application is responsible for interpreting the instance value following an agree-on schema. To review the instance value ranges provided by the agreed schema, see Presence Availability State.
To receive the above events, the application must also register for _IUccPresentityEvents on the corresponding IUccPresentity object at the beginning of a subscription session.
Receiving Notifications of Category Instance Value Modifications
When a publisher updates the value of a category instance, the subscriber receives the notification of the change in the OnCategoryInstanceValueModified event, if the subscriber registered for the event. The category context name, Name, is used to determine the strongly typed category instance to which to cast the generic category instance.
- Subscribe to the contacts category to the receive local user's contact list.
- For each contact received in the contacts subscription, advise for presentity events.
- Handle the OnCategoryContextAdded event raised by the presentity object. In the callback function, advise for category instance events whose context is received in the callback function event data argument.
- Handle OnCategoryInstanceValueModified events raised when a category instance is modified by a subscribed contact and published by Office Communications Server.
- Determine the context of the modified category instance by reading the name property of the category context property of the event source argument.
- Cast the generic IUccCategoryInstance object to the type-specific category.
- Get the interested values from the exposed properties of the new interface. If the category context name is not in the set of well-known categories, the category instance is not to be cast to a strongly typed interface. Instead, read the Value property directly from the IUccCategoryInstance object. In this case, reading the Value property returns an XML-formatted string that the client is responsible for parsing according to a custom application defined schema.