Create an IM Session
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.
A Unified Communications Client API application creates an IM session using the following pattern:
- Using the enabled endpoint object, query for the IUccSessionManager interface. In .NET-aware languages, this amounts to casting the endpoint object to the IUccSessionManager interface.
- Register for session manager events. The _IUccSessionManagerEvents interface requires two callback functions to be written in the class implementing this interface. The callback functions handle incoming IM sessions from remote users and provide a place for you to run application-specific code immediately before an outgoing session is sent to Office Communications Server.
- Create an IM session by calling CreateSession on the session manager.
For information about how to create an IUccEndpoint object, see Enable an Endpoint. In this topic, it is assumed that a valid IUccEndpoint object is already created.
IUccEndpoint endpoint = ...
//cast IUccEndpoint object to IUccSessionManager interface
IUccSessionManager sm = endpoint as IUccSessionManager;
//register for session manager events, passing the SessionManager interface instance
//as the event sink (event handler)
UCC_Advise<_IUccSessionManagerEvents>(sm, smEventHandler);
//create IM session
// Create IUccSession and store reference in private class field.
// New context object.
UccContext sessionContext = new UccContext();
// Create GUID to uniquely identify session.
string _ConversationGUID = System.Guid.NewGuid().ToString();
// Assign GUID string as session property.
// 10000 is a reserved value that causes the platform
// to insert the GUID into the outgoing session invitation.
sessionContext.AddProperty(10000, _ConversationGUID);
IUccSession session = sm.CreateSession(
(UCC_SESSION_TYPE.UCCST_INSTANT_MESSAGING,
sessionContext);
//register for session, IM session, and session participant events,
//using this object as the event sink
UCC_Advise<_IUccSessionEvents>(session, this);
UCC_Advise<_IUccInstantMessagingSessionEvents>(session, this);
UCC_Advise<_IUccSessionParticipantCollectionEvents>(session, this);
When these three tasks are completed, your application can begin inviting participants and sending messages. Remote federated participants such as Windows Live Messenger clients added to IM sessions do not receive invitations to the IM session until the first message is sent. An Office Communicator client or other Unified Communications Client API client see an invitation at the point you add them as participants to your IM session. For information about sending messages, see Send and Receive IM Messages. To review the process of adding participants to the IM session, see Invite a Participant.
In the previous code example, smEventHandler refers to an object implementing the _IUccSessionManagerEvents interface to handle the OnIncomingSession and OnOutgoingSession events. Typically, such an object controls the life time of a session manager object.
This refers to the same client object in which the session is created. It implies that the implementer of the previous code example is also responsible for implementing the _IUccSessionEvents, _IUccInstantMessagingSessionEvents, and _IUccSessionParticipantCollectionEvents interfaces.
The _IUccSessionEvents interface defines the OnAddParticipant, OnRemoveParticipant, and OnTerminate events.
A Unified Communications Client API session object raises these events:
- When the AddParticipant method is called, but before the participant is actually added to the session.
- When the RemoveParticipant method is called, but before the participant is actually removed from the session.
- When the Terminate method is called, but before the session actually ends.
These events provide a client with opportunities of perform any necessary preprocessing before the requests are submitted to the server.
The _IUccInstantMessagingSessionEvents interface defines the OnSendMessage event raised by an IM session to report the progress of the operation after the SendMessage method is called.
The _IUccSessionParticipantCollectionEvents interface defines the OnParticipantAdded and OnParticipantRemoved events. These events are raised in an IM session when a participant is actually added to and removed from a session, respectively. In practice, every Unified Communications Client API client application implements this interface and handles the events. A client can intercept these events to refresh the application’s UI elements. It can also choose to register for events that might occur in association with the newly added participant. In an IM session, a client can choose to register for the _IUccInstantMessagingSessionParticipantEvents interface on a participant object when it is actually added to the session, as is shown in the following C# example.
void _IUccSessionParticipantCollectionEvents.OnParticipantAdded(
IUccSession pEventSource,
IUccSessionParticipantCollectionEvent pEventData)
{
if (pEventData.Participant.IsLocal)
return;
if (pEventSource.Type == UCC_SESSION_TYPE.UCCST_INSTANT_MESSAGING)
{
UCC_Advise<_IUccInstantMessagingSessionParticipantEvents>(
pEventData.Participant, this);
}
// Bubble up events to the UI elements so that the display
// of this participant is properly rendered.
}
This type of registration occurs when the events defined in the _IUccInstantMessagingSessionParticipantEvents interface cannot occur until a participant is already in an IM session. This, however, is not true for events defined in the _IUccSessionParticipantEvents interface. The client must register for IUccSessionParticipantEvents events when a participant object is created.