_IUccPresentityEvents Interface

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.

Encapsulates the events raised by an IUccPresentity instance.

Namespace: Microsoft.Office.Interop.UccApi
Assembly: Microsoft.Office.Interop.UccApi (in microsoft.office.interop.uccapi.dll)

Syntax

'Declaration
Public Interface _IUccPresentityEvents
    Inherits IDispatch, IUnknown

public interface _IUccPresentityEvents : IDispatch, IUnknown

public interface class _IUccPresentityEvents : IDispatch, IUnknown

public interface _IUccPresentityEvents extends IDispatch, IUnknown

public interface _IUccPresentityEvents extends IDispatch, IUnknown

Remarks

An application must implement this interface and advise an IUccPresentity instance to receive the events when a category context is added or removed by the publisher. This is a dispinterface. Its members define the event handlers for the events raised by an IUccPresentity object. To catch the events, a UCC API client must implement these event handlers. The presentity event, OnCategoryContextAdded must be handled and the provided category context advised of an event sink for category context events. When and application receives an OnCategoryContextRemoved event, it should un-advise for the previously advised category context event. To prevent memory leaks, the client should unadvise the events when it is no longer interested in the events.

The events defined by this interface represent the top of the presentity -> category context -> category instance event hierarchy. If a client is interested in receiving updates when a user has published new or changed instances of category data, all events defined in the above hierarchy must be handled.

A client application should advise for:

1. Presentity events (_IUccPresentityEvents) for a given user (self or remote user). The client is notified when the interested presentity has added or removed a category context.

2. Category context events (_IUccCategoryContextEvents) for the given presentity. The client is notified when a category instance is added to or removed from an interested category context.

3. Category instance events (_IUccCategoryInstanceEvents) for the given category context. The client is notified when an instance value has changed in an interested category instance.

When this hierarchy of events is advised for, a local client will receive a category instance event each time any interested user publishes new category data.

It is a good idea to create a class that implements the three event interfaces referenced above. Each instance of such a class should handle the presentity, category context, and category instance events for a single user. An example of such a pattern can be seen in a class that is instantiated for each contact in a local user's contact list. Each individual contact represents a remote user (IUccPresentity)

Win32 COM/C++ Syntax

dispinterface _IUccPresentityEvents

Example

The following example handles the OnCategoryContextAdded event by determining the context name of the added context and advising that instance of an event sink if the context is one of the interested context names.

/// <summary>
/// advise for added category context when new context is
/// contactCard, state, note, or freeBusy
/// </summary>
/// <param name="pEventSource">object that raised the event</param>
/// <param name="pCategoryCtxt">event specific data</param>
void _IUccPresentityEvents.OnCategoryContextAdded(
    UccPresentity pEventSource,
    UccCategoryContextEvent pCategoryCtxt)
{

    String contextName = pCategoryCtxt.CategoryContext.Name.ToLower().Trim();
    if (contextName == "contactcard" ||
      contextName == "state" ||
      contextName == "note" ||
      contextName == "freebusy")
  {
      //Advise for category context events to get notified when
      //corresponding instances are published
      UCC_Advise<_IUccCategoryContextEvents>(
          pCategoryCtxt.CategoryContext, 
          this);
    }
}

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

_IUccPresentityEvents Members
Microsoft.Office.Interop.UccApi Namespace