Event Model of Unified Communications Client API

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 applications are intrinsically asynchronous. Typically, asynchronous applications perform multiple real-time communication and collaboration tasks. For example, while engaging the user in an IM conversation, the application monitors status change for the user's contacts and user alerts that indicate that an incoming invitation to a voice call from another user is imminent. This application scenario stipulates that Unified Communications Client API supports an asynchronous programming pattern for handling user interactions. Otherwise, for example, in a synchronized programming model, the client blocks all other calls until a task in progress finishes, leading to undesirable user experiences. Furthermore, the client lives independently from the server.

The usefulness of a Unified Communications Client API application relies on well-orchestrated interactions between the client and a server. A client sends a Session Initiation Protocol (SIP) request to Microsoft Office Communications Server and then waits for the arrival of events. Until you exit the application, events can trigger more requests, which in turn raise more events. Unified Communications Client API interfaces define what kind of operational requests a client submits. Unified Communications Client API events define what kind of event handlers a client implements to catch the events. The success of a Unified Communications Client API application depends on a full understanding of the events raised by the collection of API interfaces and the handling of those events.

The Unified Communications Client API asynchronous programming pattern follows the pattern supported by the COM event model: For every interface that returns results or other data to the caller, the client is expected to provide callback functions to receive the data. The callback functions are known as the event handlers and are defined as the members of a dispinterface for the given interface. For example, the IUccPlatform, IUccEndpoint, and IUccSession interfaces raise events specified as members of the _IUccPlatformEvents, _IUccEndpointEvents, and _IUccSessionEvents dispinterfaces, respectively.

To catch an event, the client must implement the corresponding event handler and advise the object in which the event is to be raised of the implemented event handler.

When a client is no longer interested in an event, the client should cancel the event advise action and release the event handler to help prevent memory leaks.

Advising for Event Notifications

In the Unified Communications Client API event model, the events raised by the implementation of an interface (of the IUcc* name convention) are defined by the dispinterface (of the _IUcc*Events name convention). To catch events raised by an interface, a client must implement the corresponding dispinterface and advise the IUcc* interface of the implemented event handlers. The IUcc* interface is known as the event source and the dispinterface implementation is known as the event sink.

In COM, advising the event sink of the event handlers is supported by the IConnectionPointerContainer and IConnectionPoint interfaces. To advise the event source of the corresponding event handlers, an application calls the IConnectionPoint.Advise method. To cancel the event advising action, the application calls the IconnectionPoint.Unadvise method. An example of advising for event notifications can be found in Code Listing: Basic Event Registration and Other Helper Methods in C#.

Canceling an Event Advise

Memory resources are allocated for each event advise action and are removed when the advise is canceled. Thus, to prevent memory leaks, an application should cancel every advise when it is no longer needed. An application can call the IConnectionPointer.Unadvise method to cancel a particular event advise with a given event source. The registration ID, regId, identifies this particular event advise action. An example can be found in Code Listing: Basic Event Registration and Other Helper Methods in C#.

See Also


API Object Models
Object Model of Unified Communications Client API