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.
Unified Communications Client API supports four types of sessions:
Instant Messaging Session. Two endpoints that send text messages back and forth without involving the platform media stack require the creation of an instant messaging (IM) session. This session is facilitated by the SIP stack of the platform. Participants communicate with each other with text-based messages. Because a text message is transmitted as the payload of a SIP message, there is no need to establish dedicated media channels for transmitting text messages between pairs of participating endpoints in an IM session.
Audio/Video Session. Participants communicate with each other with voice, video, or both. The multimedia content is streamed between pairs of participating endpoints through dedicated media channels separated from the underlying signaling channel. An application is responsible for establishing and maintaining such media channels in an audio/video (AV) session. An AV session includes computer-to-computer, computer-to-phone, and phone-to-phone calls. An AV session that includes endpoints separated by a firewall require proper configuration of the Media Relay component in Office Communications Server. An AV session uses the SIP stack to initiate the session and the media stack to create media channels to carry audio and video data. Video data is carried on dedicated video channels and audio is carried on dedicated audio media channels. An audio-only AV session (audio session) can involve two computer-based USB telephones. With remote call control, a client can use a PBX telephone to participate in an audio session. Special remote call control (RCC) privileges must be enabled on Office Communications Server for the user to allow the use of a PBX telephone.
Application Session. The application session is a specialized session that uses the SIP stack to transmit application information from one endpoint to the other. With an application session, two endpoints can share an application resource such as a document editor. The application session does not use the media stack or media channels. The role of an application session is to establish and maintain the connection between pairs of participating endpoints to start the application on either end and to relay the application-specific messages or data between the application instances.
Conference Session. A conference session holds a group of participants. Each participant connects to the Focus of the conference session. Participants communicate with each other indirectly through media-appropriate multipoint control units (MCUs). Each MCU is identified by a URI. Participants exchange text messages by establishing an IM session with the IM MCU, which in turn relays the messages to all the recipients in the conference session. Similarly, media is relayed from one endpoint to all the others in AV sessions established between each participant endpoint and the AV MCU. Application is shared and data is exchanged among the conference participants by application sessions (also known as collaborative sessions) established between a conference participant endpoint and the data MCU of the conference. The role of a conference session is to manage the conference, to maintain the conference roster and the list of conference participants, and to make available the supported MCUs and other conference properties. A client can let a user listen or speak to a conference without joining the conference session, provided that the client can obtain the AV MCU URI of the conference and the user has sufficient privilege.
The session types are enumerated in the UCC_SESSION_TYPE enumeration types. When creating a session, a client must supply a value that specifies the type of session. The four types of sessions can be classified as media sessions and conference sessions, depending on whether media is used in a session.
A media session is an instant messaging (IM), AV, or application session. The media in an IM session is text. The media in an AV session is audio/video stream. An application session can have custom media. All the media sessions share a common character in that the participants in such a session communicate with each other directly.
An IM session can involve more than a pair of endpoints exchanging text messages. An AV session involving more than two endpoints is handled by a Focus-based conference where each participant endpoint establishes an AV session with the AV MCU of the conference. In a media session, managing participants involves adding or removing a remote participant and establishing media channels with the remote participant. This type of session is encapsulated by the IUccInstantMessagingSession or IUccAudioVideoSession interface.
A user joins a media session by sending an invitation to one or more other users or accepting an invitation from another user. When the session is established, participants can communicate with each other until the session is terminated. The invitation comes in the form of an OnIncomingSession event regardless of whether the session is an IM, audio, or AV session. For example, creating an audio session and adding a participant whose URI is formatted as a telephone number generates an invitation on the remote client. The OnIncomingSession event provides an audio session to allow the remote client to join the audio session through the telephone session.
A conference session uses a central Focus point that acts as a peer to conference participants in a one-to-many configuration. Each individual conference participant establishes a media session with the central Focus hub. The Focus is responsible for taking IM, audio, or AV input from individual participants and broadcasting the information to the other conference participants. The Focus point is known as a multipoint control unit (MCU). Each of the four possible MCUs in a conference is dedicated to a specific media type. MCU types include:
Audio/Video. This MCU carries audio and video data generated by client devices such as webcams and Unified Communications enabled telephones. Conference topology separates Unified Communications telephone traffic from PSTN telephone traffic on different MCUs.
Data. This MCU is dedicated to application sharing within a conference.
Telephony. If conference participants are using PSTN telephones, this MCU carries the audio traffic generated by a PSTN telephone.
IM. This MCU carries the conference IM traffic.
A user joining a conference session implies only that the user has acquired the Focus of the conference and has become part of the conference roster. When inside the conference, a participant can procure the supported MCUs and choose appropriate communication means to participate in the conference. The participant cannot exchange text messages, give or listen to a speech, or share data until appropriate media sessions are established between the participant and the MCUs of the conference. If a user can obtain the MCUs of a conference through other means, for example, in an e-mail message, the user can listen to or speak in a conference, send or receive text messages, or share data without having to join the conference.
Session management for a conference involves organizing and maintaining the conference roster and the supported resources. It is encapsulated by the IUccConferenceSession interface. The functionalities common to all the sessions are encapsulated by the IUccSession interface.
Remote call control refers to the feature supported by Unified Communications Client API to enable telephony integration. This feature allows a traditional telephone on a corporate PBX to be controlled by an application, including Microsoft Office Communicator. The application can make an outgoing telephone call, answer an incoming telephone call, transfer an ongoing telephone call to another telephone set, or put a telephone call on hold and then cancel the hold later provided that such call control functionalities are enabled by the PBX. Forwarding a call is done by the server according to the routing rules published by the client. The application can query the available remote call control capabilities of the PBX by inspecting the SignalingCapabilities property on an endpoint participating in remote call control. The underlying Office Communications Server computer must be configured to support the remote call control feature.
In remote call control, a telephone set is represented by a proxy endpoint. To control the telephone set, a Unified Communications Client API client must create and enable a proxy endpoint after the controlling SIP endpoint is created and enabled. The application can do so by calling the CreateProxyEndpoint method while handling the OnEnable event that is raised by the controlling SIP endpoint.
A telephone call under the control is represented by a regular AV session between the local telephone set and a remote telephone set. In this AV session, the remote telephone set is identified by a TEL URI (for example, "TEL:+14255550100"), while the local telephone set is specified by a combination of a SIP URI (for example, "SIP:+email@example.com") and a TEL URI (for example, "TEL+14255550100"). Except for these differences, the programming pattern for remote call control is identical to a regular AV session. Making a telephone call involves creating an AV session and adding the remote telephone set into the session participant collection. To answer or forward a telephone call, implement the OnIncomingSession event raised by the controlling SIP endpoint, which acts as the manager of the AV session. Transferring an ongoing telephone call, reconnecting, and conferencing are all supported by the IUccSessionCallControl interface. For more information, see Create and Enable a Proxy Endpoint.
Unified Communications Client API exposes the following interfaces and related events to encapsulate the functionalities of sessions:
The IUccSession and _IUccSessionEvents interfaces and related API objects. These API entities encapsulate the common functionality of a session and involve maintaining and managing the session participants, inviting a user to the session, or leaving a session.
The IUccInstantMessagingSession interface and related API objects encapsulate the functionalities specific to an IM session.
The IUccAudioVideoSession interface and related API objects encapsulate the functionalities specific to an AV session.
The IUccConferenceSession interface and related API objects encapsulate the functionalities specific to a conference session.
A specialized session is also a generic session because calling QueryInterface on an IUcc*Session (where * stands for InstantMessaging, AudioVideo, Conference, Session Call Control, or Application) for an interface pointer to IUccSession results in a valid IUccSession object. However, an IM session is not a conference session because calling QueryInterface on an IUccInstantMessagingSession for an interface pointer to IUccConferenceSession results in an E_NOTINTERFACE exception.
When a client creates, for example, an IM session, the client must implement the _IUccInstantMessagingSessionEvents and _IUccSessionEvents dispinterface events, and then register them with the IM session object for event notifications (if the client is interested in the events defined in both dispinterface events). The same pattern is true for working with other session types.