Conducting an Audio/Video Session

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 audio/video session is similar to an IM session except that it requires a client to maintain a media stream outside of the SIP communications channel. The media stream carries both audio and video data and is supported by a set of audio/video interfaces obtained from session and session participant instances. Unified Communications Client API supports audio/video calls between various devices, including a computer webcam, USB phones and PSTN phones.

An audio/video session can include two user participants without requiring the support of a multipoint control unit (MCU). When more than two users are to participate, the local client must create two sessions. The first session is a peer-to-peer audio/video session where the remote peer is the conference itself. A MCU component of a conference represents the conference and has its own URI. the MCU as a remote user is added to the audio/video session as the remote participant. The second session is a conference session and provides a local user with conference related functionality such as the ability to invite additional users.

Unlike an IM session where text messages are transmitted using the existing session, an audio/video session relies on the media channels shared by the local and remote participants in a session. In the case where the local participant is invited to a session by a remote user, the remote user media channels are provided and do not need to be explicitly created. With a new outgoing audio/video session, the local client must add media channels to the remote participant before the session invitation is sent. The A/V channels must be configured to indicate the preferred direction of the media (send and/or receive) before being used in an AV session. The topics in this section cover the creation of the session, the creation of a remote participant, creation of A/V channels, addition of those channels to the session participants and addition of session participants to the session.

Important

To provide the local client with a video media stream for both preview of outbound video and viewing of inbound video, use the remote participant’s video media channel.

Certain user activities such as increasing or decreasing audio capture volume, shutting down of webcams or similar activity raise events that can be handled by media session and media channel specific event interfaces. How to handle these events is discussed in the section as well.

Before a Unified Communications Client API client can start an audio/video call, it must accomplish the following tasks:

Create and initialize the client platform. For more information, see Creating and Initializing a Platform Object.
Sign a local user in to Office Communications Server. For more information, see Sign a User into Office Communications Server.
If a PSTN telephone is used, create and initialize a proxy endpoint. For more information, see Create and Enable a Proxy 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 in addition to the session manager created for the principal endpoint. Obtain the proxy endpoint session manager from the proxy IUccEndpoint instance.

The Unified Communications Client Platform allows a client to control an audio/video session much like a traditional PSTN telephone. Sessions can be placed on hold, removed from hold, transferred, and conferenced. As was stated earlier, conferencing is an advanced functionality and is discussed in a separate section. The ability to control sessions is available using any combination of UC-enabled phones and PSTN phones. For more information, see Providing Session Call Control.

If the client uses a webcam and UC-enabled USB phone, both audio and video streams are supported. When conducting an audio/video session from a PSTN phone, audio is the only supported media modality. For information about the specific requirements of using a PSTN phone for a session, see Managing Telephone Calls.

It might be helpful to compare and contrast this programming pattern with those in IM and conference sessions. For more information, see Conducting IM Conversations and Joining and Leaving Conferences.

As in an IM session, an AV participant can initiate or receive an AV session. The programming pattern to initiate and receive an audio/video session is the same as that to initiate and receive an IM session. The initiator creates an outgoing AV session whereas the recipient accepts (or rejects) an incoming session. For information about how to handle an incoming session, see Handling Session Invitations.

A Unified Communications Client API application uses the same programming pattern for making calls between two computers and between a computer and a phone. When a client calls another computer, the participant URI is the SIP URI of the invited user, for example, "jaya@contoso.com". When the call is made to a phone, the participant URI is the SIP URI of the telephone set, for example, "sip:14255551111@ctsadomain.contoso.com". These URI strings are passed as an argument to ParseUri on a URI manager to obtain an object of UccUri type.

Programming Tasks in Carrying out a Peer-to-Peer Audio/Video Session

A media connectivity server must be configured using the IUccMediaEndpointSettings interface for audio/video calls across a firewall. For more information, see Media Connectivity Objects.

The following pseudo-code shows the general programming pattern for making an audio call. Note that the following example assumes a platform object has been initialized, a proxy endpoint has been created, and an instance of a session manager has been obtained.

A/V Session Programming Pattern

Using a session manager (IUccSessionManager), create a session by calling CreateSession and passing the UCC_SESSION_TYPE. UCCST_AUDIO_VIDEO.
Using the new session (IUccSession), create a session participant. See Performing Essential Session Tasks.
Using the new session participant, get the A/V session participant interface (IUccAudioVideoSessionParticipant)
Using the A/V session participant, create an audio and/or video channel and add the channels created to the A/V session participant.
Add the new session participant to the session. If the participant added is the remote participant, the remote user receives a session invitation.