Publish 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.

Unified Communications Client API exposes the IUccCategoryInstance interface to represent general application data used for real-time communications and collaborations. A Unified Communications Client API application can use IUccCategoryInstance and the IUccPublication interface as well as other related interfaces and events to enable a user to publish application-defined data.

Unified Communications Client API provides an enhanced presence model exposed through a series of strongly typed category instances. This presence model is useful for providing local user presence information but might not provide the data structures needed for the application-specific information a custom Unified Communications Client API client needs to publish. For information about the attributes of a category, see Category.

Using the generic IUccCategoryInstance interface, a custom application can publish data conforming to an application schema. All application-specific category data MUST be a valid XML blob published in the Value property of the category instance. The XML data published by the custom application is opaque to Office Communications Server but a remote instance of the custom application can subscribe to the category and parse the received XML data. It is the responsibility of the client to validate the XML against a custom XML schema.

The security of this application data is ensured by the proper use of ACL containers to restrict access to the published custom category.

Identifying a Unique Category Instance

An individual category instance is identified by three properties exposed by IUccCategoryInstance.

• CategoryContext. Category context is assigned to a new category instance using the first parameter of the CreatePublishableCategoryInstance method. You can create your own category context name to be used in your organization. Before publishing category instances with that name, you must register the category context name with Office Communications Server.
• ContainerId. This property is the ID of the ACL Container to which you are publishing a category instance.
• InstanceIdThe instance Id property allows you to publish multiple instances of the same category context into the same container.

Microsoft Office Communicator publishes multiple instances of category context such as contactCard into a given container in order to provide a mechanism to publish different elements of a contact card to different containers.

Publish a New Category Instance

Using Unified Communications Client API, publishing new category instances involves the following steps:

1. Obtain a publication manager (IUccPublicationManager) object from a registered endpoint (IUccEndpoint) object.

2. Register for _IUccPublicationManagerEvents events on the publication manager object.
   You must register for events if your application is to receive notifications to refresh a publication of the device expiry category instance.

3. Create one or more publishable category instances by calling the CreatePublishableCategoryInstance method
   You must specify the category name, container ID, instance ID, and expiration type for each category instance. The first three of these attributes form a unique "key" identifying a category instance. The container ID must match a container you have published. The instance ID is an arbitrary value you set but must not be the duplicate of another instance of the new category within the same container. For example, you may publish a category instance of the category context "myCategory" to container 400 and assign it the instance ID of 0. You can publish a second instance of "myCategory" to container 400, but you cannot use the instance ID of 0 for the second instance. You may also publish the expiration time. For information about category expiration, see Publication Expiration Types.
   An alternative to specifying a client application with a specific custom category name is to publish the new category instance to an existing Unified Communications Client API category. For example, specifying the category name Contacts requires a category instance cast from an IUccContact interface. Adding this category instance results in a contact being added to the user's contact list.

4. Set the Value property to an appropriate instance value for each generic category instance.
   The data type of the value is a string and must contain an XML-formatted data blob.

   Note

   When publishing strongly typed Unified Communications Client API categories, the category value is set in the appropriate derived interface rather than in the base IUccCategoryInstance.

5. Set the PublicationOperation property value to UCC_PUBLICATION_OPERATION_TYPE.UCCPOT_ADD for each category instance.

6. Create a publication (IUccPublication) object by calling the CreatePublication method.

   Note

   A publication object can contain a collection of category instances that are "batch" published with a single publish request. Thus, you can publish all desired categories with a single publish request. A publication object can only be used for a single publication action. After calling the Publish method with a set of categories, you must not publish with this publication object again. Further publication action is accomplished by creating a new publication object for each additional publish action. It is best not to dispose of a publication object until your application receives the OnPublish event for a publication.

7. Register for publication events by calling the Advise generic helper function.
   For more information about calling Advise, see Code Listing: Basic Event Registration and Other Helper Methods in C#.

8. Add each newly created category instance to the publication object
   You must call the AddPublishableCategoryInstance method and pass the category to be published in the first parameter position.

9. Finally, invoke the Publish method.

The following example publishes a new category instance to container 400.

public void PublishCategoryInstance(string value, UCC_PUBLICATION_OPERATION_TYPE pubOp)
{
    if (pubOp == UCC_PUBLICATION_OPERATION_TYPE.UCCPOT_NONE)
        return;

    string xmlValue = string.Format("<mydata>{0}</mydata>", value);

    IUccCategoryInstance cat = pubManager.CreatePublishableCategoryInstance(
              "mydata", 
              400, 
              0x20000000, 
              UCC_CATEGORY_INSTANCE_EXPIRE_TYPE.UCCCIET_STATIC, 
              0);
    if (pubOp != UCC_PUBLICATION_OPERATION_TYPE.UCCPOT_REMOVE)
        cat.Value = xmlValue;
    cat.PublicationOperation = pubOp;

    IUccPublication publication = pubManager.CreatePublication();
    publication = pubManager.CreatePublication();
    UCC_Advise<_IUccPublicationEvent>( publication, this);
    publication.AddPublishableCategoryInstance(cat);
    publication.Publish(null);
}

Update a Published Category Instance

Updating an already published category instance involves similar steps to publishing a new category instance. The additional steps amount to making a copy of the category instance to be published, updating the properties of the copied category instance, and publishing the copy.

With this copied category instance, Unified Communications Client API compares an original category instance with the instance returned in a self-subscription after the update publishing request. If the two versions of the category instance are different, the OnCategoryInstanceValueModified event is raised on the self-subscription. In the following example, the application updates a custom category by replacing the contents of the Value property with a new XML blob.

public void UpdateCategoryInstance(
                                   string value,
                                   IUccCategoryInstance pubCat)
{
    string xmlValue = string.Format("<mydata>{0}</mydata>", value);

    //Create copy of category instance from master of category instance
    IUccCategoryInstance upCat = pubCat.CreatePublishableCategoryInstance();

    //update category value in copy of instance
    upCat.Value = xmlValue;

    //set publication operation
    upCat.PublicationOperation = UCC_PUBLICATION_OPERATION_TYPE.UCCPOT_ADD;

    //create IUccPublication object if necessary
    if (publication == null)
        publication = pubManager.CreatePublication();

    //add category instance copy to publication
    publication.AddPublishableCategoryInstance(upCat);

    //publish
    publication.Publish(null);
}

This programming pattern is possible because the category instance is uniquely identifiable by the category name, instance ID, and its container ID values. The same enumeration value is used to add and update publishing operations.

Remove a Published Category Instance

Removing an already published category instance involves the obtaining of a publishable version of an existing category instance. The PublicationOperation property is set to UCC_PUBLICATION_OPERATION_TYPE.UCCOT_REMOVE and the step to set the Value property is skipped. Using the previous C# example, implement the following call to remove a published category instance.

this.PublishCategoryInstance(null, UCC_PUBLICATION_OPERATION_TYPE.UCCOT_REMOVE);

If an application advised for the category instance being removed, it is the best practice to unadvise for the category instance removed in the OnCategoryInstanceRemoved callback function for the category context of the removed instance.

void _IUccCategoryContextEvents.OnCategoryInstanceRemoved(
     IUccCategoryContext eventSource, 
     UccCategoryInstanceEvent eventData)
{
     UCC_Unadvise<_IUccCategoryInstanceEvents>( eventData.CategoryInstance, this);
}

See Also

Concepts

Category
Subscribe to Category Instances
Query Category Instances
Microsoft Office Communicator Presence Categories