This documentation is archived and is not being maintained.

_IUccCategoryContextEvents.OnCategoryInstanceAdded Method

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.

Raised when a category instance is added to the category context.

Namespace: Microsoft.Office.Interop.UccApi
Assembly: Microsoft.Office.Interop.UccApi (in

void OnCategoryInstanceAdded (
	IUccCategoryContext pCategoryCtxt,
	UccCategoryInstanceEvent pCategoryInstanceEvent
void OnCategoryInstanceAdded (
	IUccCategoryContext pCategoryCtxt, 
	UccCategoryInstanceEvent pCategoryInstanceEvent
function OnCategoryInstanceAdded (
	pCategoryCtxt : IUccCategoryContext, 
	pCategoryInstanceEvent : UccCategoryInstanceEvent



A value of the IUccCategoryContext* (IUccCategoryContext, for a .NET application) type. This specifies the category context to which the category instance is added.


A value of the IUccCategoryInstanceEvent* (UccCategoryInstanceEvent, for a .NET application) type. This specifies the event data about the category instance added to the category context.

A category context can be thought of as a collection of category instances. Each category instance in a given category context shares a common structure much the way a collection of rows in a data table share the same set of columns. A Unified Communications API client application subscribes to a category context and asynchronously receives instances of that context as events raised by the IUccCategoryContext object.

Each time a category instance is received, the OnCategoryInstanceAdded event is raised and processed by an event handler like the one in the following example. Processing a category instance involves advising for events raised by the instance itself. When the data encapsulated by the IUccCategoryInstance object has been re-published by the remote presentity, a client application must handle the corresponding OnCategoryInstanceValueModified event.

Win32 COM/C++ Syntax

HRESULT OnCategoryInstanceAdded
   IUccCategoryContext* pCategoryCtxt,
   IUccCategoryInstanceEvent* pCategoryInstanceEvent
In a Win32 application, the return value of a method or property is always an HRESULT value indicating the status of the call to the interface member. Any result of the operation is returned as a parameter marked with the [out, retval] attribute. In contrast, in a .NET application the HRESULT value indicating an error condition is returned as a COM exception and the [out, retval] parameter becomes the return value. For the UCC API-defined HRESULT values, see Trace and Handle Errors in Unified Communications Client API.

The following example handles the case where the subscribed category context is "contacts". This category represents the collection of a user's contacts. For each instance of the category context received, this event handler advises for events generated by the individual category instance. In addition, the contact category instance is the basis of a separate subscription to contact events raised by the remote user. The example event handler advises for category instance events on each received instance of the "contacts" category context.

void _IUccCategoryContextEvents.OnCategoryInstanceAdded(
    IUccCategoryContext pCategoryCtx, 
    UccCategoryInstanceEvent pCategory)
   IUccCategoryInstance ci = pCategory.CategoryInstance;

   switch (pCategoryCtx.Name.ToLower().Trim())
      case "contacts":

         //advise category instance of event sink (this)for 
         //category instance events raised
         int cookie = 0;


All public static (Shared in Visual Basic) members of this type are thread-safe. Instance members are not guaranteed to be thread-safe.

Development Platforms

Windows XP Professional with Service Pack 2 (SP2), Windows Server 2000 with Service Pack 4, Windows Server 2003, Windows Vista Ultimate Edition, Windows Vista Business Edition, Windows Vista Enterprise Edition

Target Platforms