Send and Receive IM Messages

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.

After a session is established and participants are connected, text messages can be exchanged among participants by calling the SendMessage method.

string msg = "Hello everyone!";
string msgType = "text/plain";

When there are multiple participants present in an IM session, each call of SendMessage delivers the supplied text message to all session participants except the sending participant.

session.SendMessage(msgType, msg, null);

A receiving participant receives the text message by catching the OnInstantMessageReceived event invoked on the IUccInstantMessagingSessionParticipant object. The recipient does this by implementing the _IUccInstantMessagingSessionParticipantEvents member. The following C# example provides a simple illustration.

void _IUccInstantMessagingSessionParticipantEvents.OnInstantMessageReceived(
        IUccInstantMessagingSessionParticipant pEventSource, 
        IUccIncomingInstantMessageEvent pEventData)
{
   string msg = string.Format("{0} said: {1}", 
                   pEventData.ParticipantEndpoint.Participant.Uri.Value,
                   pEventData.Content);
   MessageBox.Show(msg);
}

Before sending a message, the client can call the StartComposing method to notify the other participants that the user is in the process of typing a text message. The second parameter of this method represents the number of seconds the remote Office Communicator client should display the composing message from the local user. Federated clients using applications like Windows Live Messenger ignore the timer.

(IUccInstantMessagingSession)session.StartComposing(null);

This call triggers an OnComposing event to be raised. The other participant receives the notification in the OnComposing event, as shown in the following C# example.

void _IUccInstantMessagingSessionParticipantEvents.OnComposing(
       IUccInstantMessagingSessionParticipant pEventSource,
       IUccInstantMessagingComposingEvent pEventData)
{
   if (pEventData.ParticipantEndpoint.Participant.IsLocal)
      return;

   string msg = string.Format("{0} is typing a message",
              pEventData.ParticipantEndpoint.Participant.Uri.Value);
   MessageBox.Show(msg);
}

In a production application, the notification display probably requires a more sophisticated means than displaying a modal MessageBox window.

There are two ways to trigger the composing event, OnIdle to be raised on remote clients. The local client can call the StopComposing method to trigger the event. Alternatively, the local client can simply allow the time interval specified with the StartComposing method to expire. At that time, Unified Communications Client API automatically sends a stop composing message to all remote participants.

It is recommended that you use the MouseLeave event of the local client application text box to sense when the local user moves the mouse cursor out of the text box. When this event fires, you can write something like the following:

private void MouseOut(object sender, EventArgs e)
{
    try
    {
        if (this.thisIMSession != null)
            this.thisIMSession.StopComposing();
    }
    catch (COMException ce)
    {
        Console.WriteLine(ce.ToString());
    }
}

In this way, you ensure that remote users see that the local user has stopped composing even if the time interval set with the StartComposing method has not elapsed.

With either of these two methods, the remote participant receives the composing notification by implementing an event handler for this event, as shown in the following C# example.

void _IUccInstantMessagingSessionParticipantEvents.OnIdle(
                  IUccInstantMessagingSessionParticipant pEventSource, 
                  IUccInstantMessagingComposingEvent pEventData)
{
   if (pEventData.ParticipantEndpoint.Participant.IsLocal)
      return;

   string msg = string.Format("{0} is idle",
   pEventData.ParticipantEndpoint.Participant.Uri.Value);
   MessageBox.Show(msg);
}

Notice that the previous code checks the identity of the sending participant. In situations where there are more than two remote participants, when one participant stops composing the other can start. It is also quite possible for multiple participants to compose at the same time. You should cache received composing events to match against received idle events. As long as a remote user has sent a composing event without a corresponding idle event, the remote user continues to compose. If multiple remote participants are in the composing state, you can display something like "multiple remote users are composing." When a single remote user is composing, you should display something like "Terry Adams is composing."

See Also

Concepts

Conducting IM Conversations
Create an IM Session
Invite a Participant
End an IM Conversation