_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 microsoft.office.interop.uccapi.dll)

Syntax

'Declaration
Sub OnCategoryInstanceAdded ( _
    pCategoryCtxt As IUccCategoryContext, _
    pCategoryInstanceEvent As UccCategoryInstanceEvent _
)

void OnCategoryInstanceAdded (
    IUccCategoryContext pCategoryCtxt,
    UccCategoryInstanceEvent pCategoryInstanceEvent
)

void OnCategoryInstanceAdded (
    IUccCategoryContext^ pCategoryCtxt, 
    UccCategoryInstanceEvent^ pCategoryInstanceEvent
)

void OnCategoryInstanceAdded (
    IUccCategoryContext pCategoryCtxt, 
    UccCategoryInstanceEvent pCategoryInstanceEvent
)

function OnCategoryInstanceAdded (
    pCategoryCtxt : IUccCategoryContext, 
    pCategoryInstanceEvent : UccCategoryInstanceEvent
)

Parameters

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

• pCategoryInstanceEvent
  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.

Remarks

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
);

Example

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;
         UCC_Advise<_IUccCategoryInstanceEvents>(
            pCategory.CategoryInstance, 
            this);

         break;
      default:
         break;
   }
}

Thread Safety

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

Platforms

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

See Also

Reference

_IUccCategoryContextEvents Interface
_IUccCategoryContextEvents Members
Microsoft.Office.Interop.UccApi Namespace

Other Resources

Code Listing: Basic Event Registration and Other Helper Methods in C#