Session Participants
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.
In Unified Communications Client API, a session participant is represented by an object that implements the IUccSessionParticipant interface. Depending on the session type, the session participant object also implements one of the IUccInstantMessagingSessionParticipant, IUccAudioVideoSessionParticipant, IUccConferenceSessionParticipant, and IUccApplicationSessionParticipant interfaces.
The IUccSessionParticipant interface encapsulates the general functionality of a session participant. This includes the (SIP) URI, the state, and the location (local or remote) of a session participant.
For a type-specific session, a participant can perform different functions according to the session types. For example, in an AV session, a participant must maintain a collection of media channels to transmit media between the local and remote participants. An application session participant might need to renegotiate media description. An IM session participant is responsible for sending text messages. The mode-specific behaviors of a session participant are defined by the four type-specific session participant interfaces listed earlier.
Invite Other Participants
When a session is first created, Unified Communications Client API includes the local registered endpoint as the local participant of the session. When the local user invites another user to participate in the session, a client creates a session participant object by calling CreateParticipant and adding the resultant IUccSessionParticipant object to the session.
Following the previous implementation, the inviting client receives an OnParticipantAdded event after the invited user accepts the invitation. Similarly, if a remote participant exits the session, the client receives an OnParticipantRemoved event.
For an A/V session, which requires media channels being created in and added to the session, inviting the remote participant is more involved. The application first creates the participant object corresponding to the remote participant and a media channel. The remote participant receives the invitation after the media channel is added to the remote participant object and the remote participant object is added to the session object. Failing to do so, the OnAddParticipant event is never raised.
Session Participant Endpoints
A user can be logged on using multiple devices concurrently. A logged-on user using a particular device is represented by an endpoint object. A session represents a communication between an endpoint of a participant and an endpoint of another participant. Session participant endpoints are encapsulated by the IUccSessionParticipantEndpoint interface.
An application can choose a session participant endpoint to control how a session is established. For example, when two users talking with each other in an AV session decide to add instant messaging to exchange text messages, an application can create a new IM session using the same participant endpoints used for the existing AV session. If the endpoints are not specifically chosen, the IM invitation can be sent to each logged-on device of the remote participant.
In a conference, a participant maintains separate media sessions with the multipoint control units (MCUs) of the conference for instant messaging, audio/video calling, and application or data sharing. To handle such situations, Unified Communications Client API exposes the IUccConferenceSessionParticipantEndpoint interface. An application must use these endpoints to add media sessions in a conference.
Session Participant Events
Events that can be raised by session participants are encapsulated by the following interfaces:
- _IUccSessionParticipantEvents events inform a client when a participant endpoint is added or removed or when the state of a participant changes.
- _IUccApplicationSessionParticipantEvents events inform a client when an application-sharing (APP) session participant sends an outgoing invitation or when a participant receives, acknowledges, or accepts an invitation to join an incoming application session.
- _IUccAudioVideoSessionParticipantEvents events inform a client when an AV session participant receives updates or cancels a media request.
- _IUccInstantMessagingSessionParticipantEvents events inform a client when an IM session participant starts or stops composing, or sends or receives a text message.
- _IUccConferenceSessionParticipantEvents events inform a client when a conference session participant adds or removes a participant endpoint and sets or updates conference properties.
- _IUccConferenceSessionParticipantEndpointEvents events inform a client when media channels targeted to a participant endpoint are updated, the participant endpoint properties are updated, or its state changes.