An application can use the members of the ConferenceServicesclass to schedule, modify, or cancel a conference. The ConferenceServicesproperty on an endpoint (either UserEndpointor ApplicationEndpoint) is a reference to a ConferenceServicesobject.
Scheduling a Conference
The organizer of a conference can specify who will be allowed to participate in the conference. When the conference is scheduled, the organizer can choose from the following admission policies for the conference:
Authenticated enterprise and federated users who are explicitly included in the participant list can join the conference; any other users are denied access.
Authenticated enterprise users can join the conference, including those who are not in the participant list. Federated users who are included in the participant list are allowed into the conference.
The conference is open to everyone.
A conference organizer can also specify that public switched telephone network (PSTN) users can be included as participants. To permit PSTN users to join the conference, the following must be true:
- The conference admission policy must be
- Phone access must be enabled.
- A passcode must be set for the conference. Even if participants
are not required to enter a passcode, a passcode must be set for
the conference. For more information, see the following section,
The conference organizer can also perform other tasks using members of the ConferenceServicesclass, such as configuring the expiry time of the conference (the time when the conference will be deleted), creating the list of participants, designating which participants will be leaders, configuring a property that determines whether a passcode is required, and adding the MCUs that the conference will use (by default a conference has two MCUs, one for instant messages, and another for audio/video media).
After the conference has been scheduled, a conference organizer can retrieve a summarized list of all conferences he or she has scheduled, modify the conference information, or cancel the conference.
A PSTN user can join the conference provided that the conference organizer has scheduled the conference with the Anonymousadmission policy, and has granted phone access. To join the conference, the PSTN user dials the phone number supplied by the conference organizer, and when prompted, enters the telephone conference ID. The PSTN user may or may not be asked for a passcode for the conference, depending on whether a passcode is required. After successfully entering the required information, the PSTN user joins the conference.
Joining a Conference
An application can join an ad hocconference using the BeginJoinmethod. The Unified Communications Managed API 2.0 Core SDK schedules a conference that lasts for eight hours and adds an MCU for each ConferenceMcuSessionFactoryregistered in the platform.
Before joining the conference, it is recommended that the application register for the roster events on the ConferenceSessioninstance and the other McuSessioninstances the application is interested in.
// It is sufficient for most applications to monitor the roster on the conversation level. // Monitor new participants joining the conference. conversation.RemoteParticipantAttendanceChanged += Conversation_RemoteAttendanceChanged; // Monitor main changes to participant properties // (including local participant) such as active media types and conferencing role changes. conversation.ParticipantPropertiesChanged += Conversation_ParticipantPropertiesChanged; // Register for ConferenceSession state changes. conversation.ConferenceSession.StateChanged += ConferenceSession_StateChanged; // Register for InstantMessagingMcuSession state changes. conversation.ConferenceSession.InstantMessagingMcuSession.StateChanged += InstantMessagingMcuSession_StateChanged; // Applications that require detailed monitoring of the roster can subscribe to ConferenceSession and McuSession events. // Monitor Focus roster. conversation.ConferenceSession.ParticipantEndpointAttendanceChanged += ConferenceSession_ParticipantEndpointAttendanceChanged; // Monitor Instant Messaging MCU roster. conversation.ConferenceSession.InstantMessagingMcuSession.ParticipantEndpointAttendanceChanged += InstantMessagingMcuSession_ParticipantEndpointAttendanceChanged; conversation.ConferenceSession.InstantMessagingMcuSession.ParticipantEndpointPropertiesChanged += InstantMessagingMcuSession_ParticipantEndpointPropertiesChanged; conversation.ConferenceSession.BeginJoin(JoinCallback,state);
An application can also join a previously scheduled conference if the conference URI is known.
ConferenceJoinInformation cji = new ConferenceJoinInformation(new RealTimeAddress(conferenceURI)); conversation.ConferenceSession.BeginJoin(cji, JoinCallback, state);
An application can also join as a trusted application by setting the IsTrustedJoinproperty to true. Trusted applications automatically join conferences as leaders and are allowed elevated privileges. Trusted applications are marked as hidden participants so that ordinary clients (such as Office Communicator and LiveMeeting) do not expose their details in the conference roster to the user.
An example of a trusted application is a bot that archives instant messages sent in a conference. When the bot joins a conference as a trusted application, other clients can detect that it should be hidden from the roster.
The endpoint for an application must support elevated privileges so that it can join as a trusted application. In other words, the endpoint must be an application endpoint and the underlying collaboration platform must be initialized with a trusted GRUU.
ConferenceJoinInformation cji = new ConferenceJoinInformation(new RealTimeAddress(conferenceURI)); cji.IsTrustedJoin = true; // Indicates that the application is joining as a trusted application. conversation.ConferenceSession.BeginJoin(cji, JoinCallback, state);
When trusted applications join a conference, the ConversationParticipantobject representing the application has its RosterVisibilityproperty set to ConferencingRosterVisibility. Hidden. The UCMA 2.0 Core SDK guarantees that upon successful completion of a join operation, the ConferenceSessionstate is set to Connected. However, the state of the child MCU session (typically, an InstantMessagingMcuSessionor AudioVideoMcuSessioninstance) might be set to Activeafter the join operation completes. The first participant joining the conference signals the Focus to activate the MCUs scheduled for this conference. Office Communications Server does not guarantee that all MCUs are activated before the participant completes the join process. In fact, some MCUs might not be activated at all if they are disabled by the administrator or if an error is encountered.
Conference Commands and Events
After a successful join operation, the application is connected only to the Focus and there are no active media flows with the MCUs. For more information, see “Adding a Call to an MCU” later in this topic.
Role of the Focus in Centralized Conferencing Control Protocol (C3P)
The Centralized Conferencing Control Protocol (C3P or CCCP) defines the Focus as the central hub for roster notifications and conference commands. All MCU notifications are sent to the Focus first for aggregation and are then sent to the respective conference participants. In addition, any conference command is first sent to the Focus which then dispatches it to the appropriate MCU. Command responses are proxied back to the conference participant through the Focus as well. However, all media flows occur directly with the MCUs for efficiency.
After the ConferenceSessionstate becomes Connected, the application can issue conference commands through the ConferenceSession. The ConferenceSessionsends these commands to the Focus, which carries them out.
These commands generally impact the state of the entire conference (Focus and MCUs). Two examples are ejecting all endpoints of a specific participant from the conference, and locking the conference to prevent additional users from joining.
conversation.ConferenceSession.BeginEject(conversation.RemoteParticipants, EjectCallback, state);
Conference commands not intended for the Focus are performed by the MCUs. However, in accordance with C3P, all commands directed to the MCU are sent first to the Focus, which then proxies these commands to the MCUs. The MCUs send responses to the Focus, which then proxies the responses back to the application. This means an application can send MCU commands without having an active media flow with the MCU.
Applications can request MCU operations without the need for expensive media resources. For example, a trusted application can request the AV MCU to dial out to a PSTN user without having an active media flow with the AV MCU.
As mentioned in the previous section, an MCU can be activated after the application joins the conference. If the application invokes an McuSessionmethod before the MCU has been activated, UCMA 2.0 Core SDK queues the command and waits for up to 30 seconds for the MCU to become active and execute the command. If the MCU does not become active within this period, the command is likely to fail. For more information, see “McuSession Operations,” later in this topic.
Any changes to the conference state, such as locking a conference, are communicated by means of specific events on the ConferenceSessionclass or on McuSessionsubclasses.
The PropertiesChangedevent notifies the application of changes to the conference properties. A similar event is available for the AudioVideoMcuSessionstate to notify the application of changes to audio and video capabilities of the conference MCU.
Applications can subscribe to the RemoteParticipantAttendanceChangedevent, to be notified of new participants who join or leave the conference. Applications can also subscribe to the ParticipantPropertiesChangedevent, to be notified of changes to the participant properties (such as conferencing role and active media types). Participant active media types indicate the MCUs that the participant is connected to. For example, if Alice has only “message” as an active media type, then she is connected to the IM MCU. A participant who has no active media types is connected only to the Focus.
Applications that require more roster details can subscribe to the ParticipantEndpointAttendanceChangedand ParticipantEndpointPropertiesChangedevents on the ConferenceSessioninstance and the McuSessionsubclass instance.
The ConferenceSession. ParticipantEndpointAttendanceChangedevent notifies the application of endpoints joining and leaving the Focus. A like-named event is exposed on McuSessionsubclasses to notify an application of endpoints joining and leaving the MCU. An application can detect changes to the properties of the endpoints by the ParticipantEndpointPropertiesChangedevent.
As with conference commands, an application receives MCU-related events even if there is no active media flow with that MCU. This allows applications to monitor the roster before the media is established. For this reason, it is important for the application to register for the applicable McuSessionsubclass events before the ConferenceSession. BeginJoinmethod is called.
Adding a Call to an MCU
After the ConferenceSessionis connected, the application can add an IM call with the IM MCU to exchange instant messages with other participants. The same applies to adding an audio/video call with the AV MCU.
InstantMessagingCall imcall = new InstantMessagingCall(conversation); imcall.BeginEstablish(EstablishCallback, state);
AudioVideoCall avcall = new AudioVideoCall(conversation); avcall.BeginEstablish(EstablishCallback, state);
As previously mentioned in this topic, in the Conference Commands and Events section, an MCU can become active after the ConferenceSessionjoin operation has completed. If a call was established to an MCU that has not yet become active, the UCMA 2.0 Core SDK queues the call request and executes it within 30 seconds if the MCU becomes active. If the MCU does not become active within 30 seconds, so that the call operation fails, it is the application’s responsibility to try again, or monitor the state of the McuSessionsubclass and retry after it becomes active.
During a conference it is possible to request an MCU to dial out to another participant. The MCU initiates a call to the required destination and reports the results to the application.
An application might execute the following sample code for a situation in which two participants are in an audio conference discussing a problem and find that they need the help of a third person, Alice. One participant requests the AV MCU to dial out to the Alice’s cell phone so that she can become a conference participant.
McuDialOutOptions mcuTransferOptions = new McuDialOutOptions(); mcuDialOutOptions.ParticipantUri = "sip:email@example.com"; mcuDialOutOptions.ParticipantDisplayName = "Alice"; mcuDialOutOptions.PreferredLanguage = CultureInfo.GetCultureInfo("en-us"); conversation.ConferenceSession.AudioVideoMcuSession.BeginDialOut("tel:+14255551234", mcuDialOutOptions, dialOutCallback, state);
The preceding example demonstrates how an application can add a remote participant to the AV MCU. If no participant information is provided ( ParticipantUriand ParticipantDisplayName), UCMA 2.0 Core SDK uses the identity of the added remote participant.
Conference High Availability
The UCMA 2.0 Core SDK provides three levels of support for high availability to applications.
- Focus Front-End Failover
When the UCMA 2.0 Core SDK detects that the Focus has failed over to another Front End server, the ConferenceSessionstate changes to Reconnecting. The state of any active McuSessionsubclass instance changes to the Retryingstate. Note that any calls connected to the MCUs are not disconnected.
After failover is detected, pending conference operations fail immediately with an OperationFailureExceptionwith FailureReasonset to SessionRetrying. Any Begin Xxxmethod invoked on the ConferenceSessionor an McuSessionsubclass fails with a RealTimeInvalidOperationExceptionwith FailureReasonset to RetryableOperation.
The ConferenceSessionattempts to reconnect to the conference only once. If that attempt fails, the ConferenceSessionis terminated, otherwise the state of the ConferenceSession is again changed to the Connectedstate. A fresh roster notification is sent and events are raised for any changes that occur during the reconnection process. The state of the McuSessionsubclass changes again to active when the MCUs are reported to be activated on the server.
- MCU Failover
During conference activation, an MCU can failover to another Front End server. The corresponding McuSessionstate is changed to Retryingand the call with the MCU is terminated. The application can reestablish the call after the MCU becomes active again.
- Intermediate Hop Failover
ConferenceSessionand McuSessionsubclasses support SIP dialog resiliency. If an intermediate hop fails when a conference command is sent, UCMA 2.0 Core SDK attempts to repair the route automatically. If the repair process fails, the ConferenceSessionis terminated and pending commands fail.