Conducting IM Conversations

Article
06/14/2014

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.

An IM session is a collaboration session that uses client to server Session Initiation Protocol (SIP) communication to pass text messages from a local client to an instance of Office Communications Server to a remote client. The IM session interface exposes methods and properties that support the sending and receiving of text messages. In addition, the IM session interface allows two IM session participants to notify and receive notification of composing activity.

An IM session is usually a peer-to-peer session involving just two participants. The IM modality can also be used in a conference session involving many participants. In both cases, the specifics of IM are handled by the IUccInstantMessagingSession interface. You should be familiar with the general aspects of Communicating with Remote Users before working with IM sessions.

This section builds on general session tasks and provides examples specific to an IM session. In general, the unique aspect of an IM session is messaging functionality. The exchange of text messages within an IM session is accomplished using both the IUccInstantMessagingSession and the IUccInstantMessagingSessionParticipant interfaces. Although a custom application can encapsulate IM functionality within a general session class, it is better to provide a new application class that handles the specific IM functionality. It is a good idea to instantiate such a class and give it a reference to the instance of IUccSession provided in an IM invitation or created to invite a remote user. This is the programming pattern followed by the code examples used in this section.

Although a client must create a platform, endpoint, and session manager whether it is initiating or accepting invitations, it must follow different programming patterns for initiating and accepting an invitation after the session manager is created.

Task Overview

Before a Unified Communications Client API client can accept an IM invitation or invite a remote user to an IM conversation, it must accomplish several tasks. These include:

Creating and initializing a platform object. The platform object is the foundation of all other Unified Communications Client API functionality. For more information, see Creating and Initializing a Platform Object.
Creating and enabling an endpoint. For more information, see Create a Principal Endpoint.
Creating a session manager on the endpoint. If a proxy endpoint is created in addition to a SIP endpoint, a session manager must be created for the proxy endpoint. The session manager is the origin of all session-related events and the factory object responsible for creating a session.

Participating in IM Sessions

A client can either invite a remote participant to a new session or accept a session from a remote participant in an invitation.

To Invite a Remote User

Using the session manager, create an session specifying the modality type as IM. See Performing Essential Session Tasks for information about creating sessions.
Invite a participant by creating and adding it to the session.

Important

The Unified Communications Client Platform API does not support multiple remote participants in a peer-to-peer session. Schedule a conference and invite remote participants if you want to have three or more participants

To Accept an Invitation from a Remote User

Register for a session invitation by advising for _IUccSessionManagerEvents. See Handling Session Invitations for information about session manager event handling.
Accept incoming session by handling OnIncomingSession.

Important

An incoming session is complete with all properties necessary to carry on an IM session. The local client does not add either a local or remote participant to the session.

To Participate in a New IM Session

Cast the general IUccSession interface to IUccInstantMessagingSession so the client can access IM specific methods and properties.
Advise for instant messaging events exposed by _IUccInstantMessagingSessionEvents.
Advise for instant messaging session participant events exposed by _IUccInstantMessagingSessionParticipantEvents.
Send text messages to the participants in the IM session.
Receive text messages from participants.
Continue to send and receive messages.