See Also 
In Office Communicator Automation API, a method or property on an interface can be synchronous or asynchronous. For example, the IMessenger::GetContact method is synchronous: the application is blocked until the call is returned, with a result in this case. An example of an asynchronous method is the IMessenger::AutoSignin method. The call returns immediately, but the resulting effects are communicated back in an event at a later time. Also, changing the status of a client in the connected Communicator instance is asynchronous as well. A user can change the status from the Communicator user interface. The application receives a notification of such a change provided that the application has subscribed to notifications of such an event.
If you are creating a custom contact list in your application, you need to be aware of the asynchronous nature of some of the interface methods you will be using. For example, IMessenger::AddContact does not block your application while awaiting the result of the method call. If you rebuild your contact list immediately after making the method call, you might not see your new contact. Subscribing to the DMessengerEvents::OnContactListAdd event allows your application to rebuild the custom contact list after the Office Communicator server has finished adding the contact. For more information about building and maintaining a custom contact list, see Building a Custom Contact List.
Subscribing to Event Notifications
in C#
In a C# application, subscribing to event notification amounts to registering an event handler with the object in which the event is raised. Valid signatures of event handlers are documented in the Events section of Office Communicator Automation API Reference.
The following code snippet illustrates how to register an event handler to receive notifications from a connected Communicator instance when the status of a contact changes.
 Copy Code |
|
|---|---|
// Create a Messenger object using the API communicator = new CommunicatorAPI.Messenger(); // Register OnContactStatusChange event handler communicator.OnContactStatusChange += new DMessengerEvents_OnContactStatusChangeEventHandler(OnContactStatusChange); |
|
Receiving Events in C#
When an event is raised, the event source calls an appropriate event handler that has been registered with the event source. An application implements the event handler to receive and, hence, process the event. The following C# code snippet offers a simple implementation to handle contact status change events: displaying the name and new status of a contact.
| Copy Code |
|
|---|---|
void OnContactStatusChange(object pMContact, MISTATUS mStatus)
{
IMessengerContact contact = pMContact as IMessengerContact;
string status = Enum.GetName(typeof(MISTATUS), mStatus);
string msg = contact.FriendlyName + " : " + status;
System.Windows.Forms.MessageBox.Show(msg);
}
|
|
The signature of this event handler is defined in the DMessengerEvents::OnContactStatusChange event.
Event Handling in C++
Event handling in C++ involves implementing and handling the IConnectionPoint, IConnectionPointContainer and related interfaces on both ends of an event chain (source and sink). The programming pattern is much more complex than that in C# (and other .NET framework compliant programming languages), as discussed above. An application developer can use Active Template Library (ATL) or coding from scratch. A sample of using ATL can be found at (http://support.microsoft.com/?kbid=181277). Coding from scratch is even more challenging; however, a determined user can find the necessary technical information on MSDN (http://msdn.microsoft.com).