_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 microsoft.office.interop.uccapi.dll)
Syntax
'Declaration
Sub OnInstantMessageReceived ( _
pEventSource As UccInstantMessagingSessionParticipant, _
pEventData As UccIncomingInstantMessageEvent _
)
void OnInstantMessageReceived (
UccInstantMessagingSessionParticipant pEventSource,
UccIncomingInstantMessageEvent pEventData
)
void OnInstantMessageReceived (
UccInstantMessagingSessionParticipant^ pEventSource,
UccIncomingInstantMessageEvent^ pEventData
)
void OnInstantMessageReceived (
UccInstantMessagingSessionParticipant pEventSource,
UccIncomingInstantMessageEvent pEventData
)
function OnInstantMessageReceived (
pEventSource : UccInstantMessagingSessionParticipant,
pEventData : UccIncomingInstantMessageEvent
)
Parameters
- pEventSource
A value of the IUccInstantMessagingSessionParticipant* (UccInstantMessagingSessionParticipant, for a .NET application) type. This identifies the IM participant sending the message.
- pEventData
A value of the IUccIncomingInstantMessageEvent* (UccIncomingInstantMessageEvent, for a .NET application) type. This contains the information about the received message.
Remarks
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
);
Note
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 .
Example
The example handles the OnInstantMessageReceived event. The ContentType property is examined to determine the correct text processing logic to execute.
Note
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)
{
this.rt_SendText.Clear();
this.rt_SendText.Refresh();
}
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
this.rt_ReceiveText.LoadFile(
inputStream,
RichTextBoxStreamType.RichText);
}
}
else
{
this.rt_ReceiveText.AppendText(
pEventData.ParticipantEndpoint.Participant.Uri.User +
": ");
this.rt_ReceiveText.AppendText(
pEventData.Content);
}
//select bottom of textbox;
this.rt_ReceiveText.ScrollToCaret();
this.rt_ReceiveText.Refresh();
}
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
_IUccInstantMessagingSessionParticipantEvents Interface
_IUccInstantMessagingSessionParticipantEvents Members
Microsoft.Office.Interop.UccApi Namespace