This documentation is archived and is not being maintained.

_IUccInstantMessagingSessionParticipantEvents.OnInstantMessageReceived 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 new message from a specified participant is received.

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

void OnInstantMessageReceived (
	UccInstantMessagingSessionParticipant pEventSource,
	UccIncomingInstantMessageEvent pEventData
void OnInstantMessageReceived (
	UccInstantMessagingSessionParticipant pEventSource, 
	UccIncomingInstantMessageEvent pEventData
function OnInstantMessageReceived (
	pEventSource : UccInstantMessagingSessionParticipant, 
	pEventData : UccIncomingInstantMessageEvent



A value of the IUccInstantMessagingSessionParticipant* (UccInstantMessagingSessionParticipant, for a .NET application) type. This identifies the IM participant sending the message.


A value of the IUccIncomingInstantMessageEvent* (UccIncomingInstantMessageEvent, for a .NET application) type. This contains the information about the received message.

OnInstantMessageReceived must be handled in order to carry on an instant messaging conversation. The remote sending user receives confirmation that a message was sent and received by the local endpoint regardless of whether the local application has advised for _IUccInstantMessagingSessionParticipantEvents.

The event data argument of this callback method provides both the actual content of the sent message and the MIME content text subtype of the message. Normally, message are sent in the "text/plain" MIME content format, but messages can also be sent as "text/enriched" or "text/html".

Win32 COM/C++ Syntax

HRESULT OnInstantMessageReceived
   IUccInstantMessagingSessionParticipant* pEventSource,
   IUccIncomingInstantMessageEvent* pEventData
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 example handles the OnInstantMessageReceived event. The ContentType property is examined to determine the correct text processing logic to execute.

The following example assumes an instance of System.Windows.Forms.RichTextBox (this.rt_ReceiveText) has been declared and instantiated in the application class containing this example method. The example cannot compile without a class instance of this.rt_ReceiveText

/// <summary>
/// displays incoming instant message text in either a TextBox instance or
/// a RichTextBox instance, depending on the MIME content text subtype specified
/// </summary>
/// <param name="pEventSource">UccInstantMessagingSessionParticipant participant sending the message</param>
/// <param name="pEventData">UccIncomingInstantMessageEvent The message</param>
void _IUccInstantMessagingSessionParticipantEvents.OnInstantMessageReceived(
    UccInstantMessagingSessionParticipant pEventSource, 
    UccIncomingInstantMessageEvent pEventData)
    IUccSessionParticipant sendingParticipant = pEventSource as IUccSessionParticipant;
    if (this.rt_ReceiveText.Text.Length > 0)

    if (pEventData.ContentType == "text/enriched")
        //create a MemoryStream to stream the received
        //rich text bytes into the RichTextBox
        using (System.IO.MemoryStream inputStream = new System.IO.MemoryStream())

            //convert input string as char array into a byte array
            byte[] inputbytes = new byte[pEventData.Content.Length];
            string byteString = pEventData.Content;
            for (int i = 0; i < byteString.Length; i++)
                Char c = byteString[i];
                inputbytes[i] = Convert.ToByte(c);

            //set capacity of memory stream to length of message
            inputStream.Capacity = inputbytes.Length;

            //write the whole byte array to the memory stream
            inputStream.Write(inputbytes, 0, inputbytes.Length);

            //set memory stream pointer to beginning of the stream
            inputStream.Seek(0, System.IO.SeekOrigin.Begin);

            //load memory stream into the rich text box as RichText
            pEventData.ParticipantEndpoint.Participant.Uri.User + 
            ": ");

    //select bottom of textbox;

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