ConferenceSession

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.

The ConferenceSession class implements the signaling functionality of a Centralized Conference Control Protocol (C3P) conference signaling session.

ConferenceSession State Transitions

The following illustration shows the possible state transitions on a ConferenceSession instance.

1. The transition from Idle to Connecting occurs when BeginJoin is called.

2. The transition from Connecting to Connected occurs when the join process is complete. In the Connected state, ParticipantEndpointAttendanceChanged events are raised for all existing participant endpoints in the Focus and MCUs before the callback method in the argument list of BeginJoin is called.

3. The transition from Connected to Terminating occurs when any of the following occur:

   • The application called BeginTerminate on the Conversation instance.

   • The application called BeginTerminateConference on the ConferenceSession instance.

   • A local participant was ejected from the conference.

   • The conference was terminated.

   • The parent Conversation failed an escalation attempt.

4. The transition from Terminating to Terminated occurs when the application calls BeginTerminateConference on the ConferenceSession instance. The termination process is complete. Signaling and subscription sessions with the Focus are terminated before this transition occurs.

5. The transition from to Terminating to Idle occurs only when the parent Conversation has failed an escalation attempt. Before the transition to Idle occurs, ConferenceSession state is cleaned up and ParticipantEndpointAttendanceChanged events are raised for all participant endpoints associated with this ConferenceSession and its child McuSession objects.

6. The transition from Connected to Reconnecting occurs if the front end that hosts the Focus has failed over. During this transition, all pending ConferenceSession operations fail. Any operation requested from ConferenceSession after its state changes to Reconnecting will fail with a RealTimeInvalidOperationException with a failure reason of RetryableOperation.

7. The transition from Reconnecting to Connected occurs when the reconnection process is successful. The Focus delivers a fresh roster that is compared to the existing roster information in ConferenceSession and its McuSession objects. Events are raised if any differences are detected.

8. The transition from Reconnecting to Terminating occurs if the reconnection attempt fails. Note that only one reconnection attempt is made.

9. The transition from Connecting to Idle occurs when the connection attempt fails, whereupon EndJoin throws an exception.

   Note

   Conversation as currently implemented will begin terminating if an attempt to join a conference fails but the ConversationState on the Conversation instance is not Conferencing.

ConferenceSession Constructors

The ConferenceSession class has no public constructors.

ConferenceSession Properties

The following are the public properties on the ConferenceSession class.

// Gets conversation that holds this signaling session.
// For an outgoing session, the conversation is not available until the session 
// is bound to a conversation. However, the conversation is available on an incoming session 
// because it is already bound to a conversation by the time it is exposed to the application.
public Conversation Conversation {get;}

// Gets the state of the conference.
public ConferenceSessionState State {get;}

// Gets whether a conference is locked.
public bool IsLocked {get;}

// Gets the source network of the conference being hosted.
public SourceNetwork HostingNetwork {get;}

// Gets the conference URI.
public string ConferenceUri {get;}

// Gets the XML data given to all clients when they join.
public string ParticipantData {get;}

// Gets or sets whether to join the conference as a trusted application.
// An endpoint supporting privileged operations is required to join as a trusted application.
// Trusted applications always join a conference as trusted leaders and they are able to carry out privileged operations.
// A trusted application appears as a hidden participant in the roster.
public bool IsTrustedJoin {get; set;}

// Gets the disclaimer that should be presented to the user prior to joining.
// Some administrators may wish to configure a message that clients can display before the join.
public string Disclaimer {get;}

// Gets the conference subject.
public string Subject {get;}

// Gets the instant messaging MCU session.
public InstantMessagingMcuSession InstantMessagingMcuSession {get;}

// Gets the audio video MCU session.
public Microsoft.Rtc.Collaboration.AudioVideo.AudioVideoMcuSession AudioVideoMcuSession {get;}

ConferenceSession Methods

The following are the public methods on the ConferenceSession class.

// Attempts to retrieve an McuSession of type T.
public bool TryGetMcuSession<T>(out T existingMcuSession) where T : McuSession;

// Converts a ConferenceSession to its address for later rejoin.
public static implicit operator RealTimeAddress(ConferenceSession session);

// Creates and joins a conference based on current conversation media.
public IAsyncResult BeginJoin(AsyncCallback userCallback, object state);

// Creates and joins a conference based on current conversation media.
public IAsyncResult BeginJoin(
    ConferenceJoinInformation information,
    AsyncCallback userCallback, 
    object state);

// Waits for the pending asynchronous join operation to complete.
// The conference session state will transition to connected if the join operation is successful. If unsuccessful, the conference session 
// cleans up its state and transitions to idle.
// The join operation fails if the conference was locked and the local participant was placed in conference lobby. 
public void EndJoin(IAsyncResult result);

// Terminates the conference and forces all participants to leave, if performed by a conference leader.
// Otherwise it causes the participant to leave the conference.
// Conversation.Terminate is the preferred way to leave a conference. 
public IAsyncResult BeginTerminateConference(
    AsyncCallback userCallback,
    object state);

// Gets the results from terminating the conference.
public void EndTerminateConference(
    IAsyncResult result);
   
// Removes a participant from the conference.
public IAsyncResult BeginEject(
    ConversationParticipant participant,
    AsyncCallback userCallback,
    object state);

// Waits for the pending operation to complete.
public void EndEject(
    IAsyncResult result);

// Locks a conference.
public IAsyncResult BeginLockConference(
    AsyncCallback userCallback,
    object state);

// Waits for the pending operation to complete.
public void EndLockConference(
    IAsyncResult result);

// Unlocks a conference.
public IAsyncResult BeginUnlockConference(
    AsyncCallback userCallback,
    object state);

// Waits for the pending operation to complete.
public void EndUnlockConference(
    IAsyncResult result);

// Changes the role of the participant in the conference.
public IAsyncResult BeginModifyRole(
    ConversationParticipant participant,
    ConferencingRole role,
    AsyncCallback userCallback,
    object state);

// Waits for the pending operation to complete.
public void EndModifyRole(
    IAsyncResult result);

// Gets the MCU address for the specified category.
public McuInformation GetMcuInformation(string mcuType);

// Returns a list of all remote participants.
public Collection<ParticipantEndpoint> GetRemoteParticipantEndpoints();
 
// Returns a list of local participant endpoint on the Focus that are waiting to be approved for entry in the conference.
public Collection<ParticipantEndpoint> GetLocalParticipantEndpoints();

// Gets the properties for the given participant endpoint.
public bool TryGetParticipantEndpointProperties(
    ParticipantEndpoint endpoint,
    out ConferenceParticipantEndpointProperties properties);

// Returns a System.String that represents this object.
public override string ToString();

ConferenceSession Events

The following are the public events on the ConferenceSession class.

// Raised when participant endpoints join or leave the conference.
public event EventHandler<ParticipantEndpointAttendanceChangedEventArgs<ConferenceParticipantProperties>> ParticipantEndpointAttendanceChanged;

// Raised when a property changes on a participant endpoint.
public event EventHandler<ParticipantEndpointPropertiesChangedEventArgs<ConferenceParticipantEndpointProperties>> ParticipantEndpointPropertiesChanged;

// Raised when a property changes on the conference.
public event EventHandler<PropertiesChangedEventArgs<ConferenceSessionProperties>> PropertiesChanged;

// Raised when session state changes.
public event EventHandler<StateChangedEventArgs<ConferenceSessionState>> StateChanged;