Share via

Conference Scheduling and Management

  • Article

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 application can use the members of the ConferenceServices class to schedule, modify, or cancel a conference. The ConferenceServices property on an endpoint (either UserEndpoint or ApplicationEndpoint) is a reference to a ConferenceServices object.

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:

  • ClosedAuthenticated
    Authenticated enterprise and federated users who are explicitly included in the participant list can join the conference; any other users are denied access.

  • OpenAuthenticated
    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.

  • Anonymous
    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:

  1. The conference admission policy must be Anonymous.

  2. Phone access must be enabled.

  3. 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, PSTN Participants.

The conference organizer can also perform other tasks using members of the ConferenceServices class, 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.

PSTN Participants

A PSTN user can join the conference provided that the conference organizer has scheduled the conference with the Anonymous admission 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 hoc conference using the BeginJoin() method. The Unified Communications Managed API 2.0 Core SDK schedules a conference that lasts for eight hours and adds an MCU for each ConferenceMcuSessionFactory registered in the platform.

Before joining the conference, it is recommended that the application register for the roster events on the ConferenceSession instance and the other McuSession instances 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 IsTrustedJoin property 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 ConversationParticipant object representing the application has its RosterVisibility property set to ConferencingRosterVisibility.Hidden. The UCMA 2.0 Core SDK guarantees that upon successful completion of a join operation, the ConferenceSession state is set to Connected. However, the state of the child MCU session (typically, an InstantMessagingMcuSession or AudioVideoMcuSession instance) might be set to Active after 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.

ConferenceSession Commands

After the ConferenceSession state becomes Connected, the application can issue conference commands through the ConferenceSession. The ConferenceSession sends 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[0], EjectCallback, state);

conversation.ConferenceSession.BeginLockConference(LockConferenceCallback, state);

McuSession Commands

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 McuSession method 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.

Conference Events

Any changes to the conference state, such as locking a conference, are communicated by means of specific events on the ConferenceSession class or on McuSession subclasses.

The PropertiesChanged event notifies the application of changes to the conference properties. A similar event is available for the AudioVideoMcuSession state to notify the application of changes to audio and video capabilities of the conference MCU.

Applications can subscribe to the RemoteParticipantAttendanceChanged event, to be notified of new participants who join or leave the conference. Applications can also subscribe to the ParticipantPropertiesChanged event, 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 ParticipantEndpointAttendanceChanged and ParticipantEndpointPropertiesChanged events on the ConferenceSession instance and the McuSession subclass instance.

The ConferenceSession.ParticipantEndpointAttendanceChanged event notifies the application of endpoints joining and leaving the Focus. A like-named event is exposed on McuSession subclasses to notify an application of endpoints joining and leaving the MCU. An application can detect changes to the properties of the endpoints by the ParticipantEndpointPropertiesChanged event.

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 McuSession subclass events before the ConferenceSession.BeginJoin method is called.

Adding a Call to an MCU

After the ConferenceSession is 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 ConferenceSession join 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 McuSession subclass and retry after it becomes active.

McuSession Operations

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:alice@contoso.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 (ParticipantUri and 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.

  1. Focus Front-End Failover

    When the UCMA 2.0 Core SDK detects that the Focus has failed over to another Front End server, the ConferenceSession state changes to Reconnecting. The state of any active McuSession subclass instance changes to the Retrying state. Note that any calls connected to the MCUs are not disconnected.

    After failover is detected, pending conference operations fail immediately with an OperationFailureException with FailureReason set to SessionRetrying. Any BeginXxx method invoked on the ConferenceSession or an McuSession subclass fails with a RealTimeInvalidOperationException with FailureReason set to RetryableOperation.

    The ConferenceSession attempts to reconnect to the conference only once. If that attempt fails, the ConferenceSession is terminated, otherwise the state of the ConferenceSession is again changed to the Connected state. A fresh roster notification is sent and events are raised for any changes that occur during the reconnection process. The state of the McuSession subclass changes again to active when the MCUs are reported to be activated on the server.

  2. MCU Failover

    During conference activation, an MCU can failover to another Front End server. The corresponding McuSession state is changed to Retrying and the call with the MCU is terminated. The application can reestablish the call after the MCU becomes active again.

  3. Intermediate Hop Failover

    ConferenceSession and McuSession subclasses 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 ConferenceSession is terminated and pending commands fail.