Schedule a Conference
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.
Scheduling a conference on Office Communications Server involves instantiating an IUccConferenceInformation object, instantiating an optional operation context object, calling into the ScheduleConference method of the conference session manager, advising for the conference scheduling event, and handling that event.
Scheduling a conference involves the following programming tasks:
- Setting conference information properties
- Scheduling the conference
- Handling conference scheduling events
The conference Focus URI for a newly scheduled conference is returned to the scheduling user in this event.
Setting conference information properties
The IUccConferenceInformation interface provides the properties necessary to configure and schedule a conference. The conference information object provides the Focus Factory component of Office Communications Server with everything from the invitee list to the MCU resources needed to host the conference. If you want to modify a scheduled conference, get a conference information object representing the conference to be modified from the Focus Factory, change the interested properties, and post the conference information object back to the Focus Factory.
The ConferenceId property is assigned by Unified Communications Client API when the IUccConferenceInformation object is created. This property represents the unique identifier of the conference. Use the conference ID for further conference operational request on the server. For example, to delete a conference, pass this conference ID as the first argument to the DeleteConference method.
The conference ID is also available as part of the URI of the conference itself. When you request a list of scheduled conferences using the GetConferenceList method, you receive a collection of IUccConferenceInformation objects representing the individual conferences. These objects can be individually examined to get the conference ID for each conference in the collection. For an example, see Conference Manager Sessions.
The conference key is used by an anonymous user who does not have an enterprise entity. If this user has a PIN number and the conference key, he can join the conference. If a conference key is not provided by your application when a conference is scheduled, Unified Communications Client API generates one. The ConferenceKey is a read/write property of the conference information object.
Using the UCC_CONFERENCE_INFORMATION_PROPERTY enumeration, the conference information object provides all the conference configuration properties to set:
- Admission type. The property represented by UCCCIP_ADMISSION_TYPE can have values represented by the UCC_CONFERENCE_ADMISSION_TYPE enumeration.
- Expiry Time. The expiry time property represented by UCCCIP_EXPIRY_TIME specifies the date and time a scheduled conference expires. The list of your scheduled conferences returned from the Focus Factory server does not include conferences whose expiry time has been reached.
- MCUs. The conference can be configured to use any of the multipoint control units configured on the Office Communications Server computer hosting the conference. Use this property to specify the collection of MCUs to be used in a conference. Use the UCCCIP_MCUS enumeration value to set or retrieve this property.
The MCUs property is a collection of MCUs which are in turn a collection of MCU attributes. Attributes are added to an MCU (also known as a conference entity), conference entities are added to an entity collection, and the entity collection is added as the MCUs property of the conference information object. - Notification Data. This property represented by the enumeration value UCCCIP_NOTIFICATION_DATA, holds an XML string that contains the notification data that is displayed on first entry for each participant.
- Organizer Roaming Data. The organizer roaming data property is an XML string containing the information a conference organizer needs when she logs into a Unified Communications Client API application to enter or reconfigure a conference.
- Participants. This property, which is represented by UCCCIP_PARTICIPANTS, holds a collection of participants. Each participant is in turn represented by a property collection enumerated using UCC_CONFERENCE_PARTICIPANT_PROPERTY.
- Subject. The subject property, which is represented by UCCCIP_SUBJECT, contains a string used to display the subject of the conference.
Conference Information Properties Example
The C# sample code demonstrates setting some of the configuration properties of a conference. Note that if a conference admission type is UCCCAT_CLOSED_AUTHENTICATED, you must provide a participants roster.
/// <summary>
/// Creates a conference information object for conference scheduling
/// </summary>
/// <returns>UccConferenceInformation new conference info class instance</returns>
private UccConferenceInformation CreateConferenceInfo(
string pConferenceSubject,
UCC_CONFERENCE_ADMISSION_TYPE pAdmissionType)
{
string subjectString = pConferenceSubject;
UccConferenceInformation ci = this.myConfManagerSession.CreateConferenceInformation();
// Store UCCP assigned Conference Id in local string.
string confId = ci.ConferenceId;
IUccPropertyCollection cPC = ci.Properties;
if (pAdmissionType == UCC_CONFERENCE_ADMISSION_TYPE.UCCCAT_CLOSED_AUTHENTICATED)
{
// Add the participants.
// Create property collection for all invited users.
IUccPropertyCollection m_pUserList = new UccPropertyCollectionClass();
// Create property collection representing a user.
IUccPropertyCollection oneUser = new UccPropertyCollectionClass();
foreach (object userSIPUri in this._conferenceInviteeList)
{
// Add user URI to user property collection.
UccUri userUri = userSIPUri as UccUri;
oneUser.AddProperty(
(int)UCC_CONFERENCE_PARTICIPANT_PROPERTY
.UCCCPPID_URI,
userUri.AddressOfRecord);
// Add user role to user property collection.
oneUser.AddProperty(
(int)UCC_CONFERENCE_PARTICIPANT_PROPERTY
.UCCCPPID_ROLE,
UCC_CONFERENCE_PARTICIPANT_ROLE
.UCCCPR_PARTICIPANT);
// Add single user invited to invited user list collection.
m_pUserList.AddProperty(1, oneUser);
}
// Cast IUccPropertyCollection to IUccCollection so Count method is
// exposed.
IUccCollection mUserCollection = m_pUserList as IUccCollection;
if (mUserCollection != null)
{
if (mUserCollection.Count > 0)
{
// Add user list collection as a property to the conference
// property collection.
cPC.AddProperty(
(int)UCC_CONFERENCE_INFORMATION_PROPERTY
.UCCCIP_PARTICIPANTS,
m_pUserList);
}
}
else
{
Console.WriteLine("casting userList to UccCollection failed");
}
}
cPC.AddProperty(
(int)UCC_CONFERENCE_INFORMATION_PROPERTY.UCCCIP_ADMISSION_TYPE,
pAdmissionType);
cPC.AddProperty(
(int)UCC_CONFERENCE_INFORMATION_PROPERTY.UCCCIP_SUBJECT,
"Conference Subject");
DateTime dt;
int mins = 59;
TimeSpan ts = new TimeSpan(0, 0, mins, 0);
// Get current time expressed as coordinated universal time
// and add 59 minutes to the current time. The meeting will expire in 59 minutes.
dt = DateTime.UtcNow;
dt = dt.Add(ts);
cPC.AddProperty(
(int)UCC_CONFERENCE_INFORMATION_PROPERTY.UCCCIP_EXPIRY_TIME,
dt);
IUccPropertyCollection pMCU = new UccPropertyCollectionClass();
IUccPropertyCollection _MCUCollection = new UccPropertyCollectionClass();
//add attribute properties to an MCU
pMCU.AddProperty(
(int)UCC_CONFERENCE_ENTITY_SETTING_PROPERTY.UCCCESP_TYPE,
(int)UCC_CONFERENCE_ENTITY_TYPE.UCCCET_AUDIO_VIDEO);
//add MCU to the MCU (conference entity) collection
_MCUCollection.AddProperty(
(int)UCC_CONFERENCE_ENTITY_TYPE.UCCCET_AUDIO_VIDEO, pMCU);
//add attribute properties to an MCU
pMCU.AddProperty(
(int)UCC_CONFERENCE_ENTITY_SETTING_PROPERTY.UCCCESP_TYPE,
(int)UCC_CONFERENCE_ENTITY_TYPE.UCCCET_INSTANT_MESSAGING);
//add MCU to the MCU (conference entity) collection
_MCUCollection.AddProperty(
(int)UCC_CONFERENCE_ENTITY_TYPE.UCCCET_INSTANT_MESSAGING, pMCU);
//add MCU collection to the conference information object
cPC.AddProperty(
(int)Microsoft.Office.Interop.UccApi.UCC_CONFERENCE_INFORMATION_PROPERTY.UCCCIP_MCUS,
_MCUCollection);
return ci;
}
Scheduling the Conference
After the conference properties are set using the IUccConferenceInformation interface and an optional IUccOperationContext is initialized, scheduling the conference amounts to a single method call. The example C# code illustrates this call.
Creating an operation context object and passing it as an argument to ScheduleConference allows the OnScheduleConference callback function to obtain the context of this conference scheduling request. The example C# code is using the Unified Communications Client API assigned conference ID as a context value. The OnScheduleConference event does not return the conference information object. If you want to use conference configuration values in the event handler, you must pass them using the operation context.
/// <summary>
/// Creates a new conference on a Focus server
/// </summary>
/// <param name="pInvitees">List collection of UccUri objects</param>
public void ScheduleNewConference(List<object> pInvitees)
{
if (pInvitees == null || pInvitees.Count == 0)
{
return;
}
this._conferenceInviteeList = pInvitees;
// Create a conference manager.
if (this.myConferenceManager == null)
{
this.myConferenceManager = this.myPlatform.ServerEndpoint as IUccConferenceManager;
}
// Create a new conference manager session to be used to create the actual conference.
this.myConfManagerSession = this.myConferenceManager.CreateConferenceManagerSession(
this.myPlatform.ServerConfiguration.FocusFactory);
// Advise for conference manager session events.
UCC_Advise<_IUccConferenceManagerSessionEvents>(
this.myConfManagerSession,
this);
UccOperationContext mcuOperationContext = new UccOperationContextClass();
UccContext mcuContext = new UccContextClass();
mcuContext.AddNamedProperty("ScheduleConference", true);
mcuOperationContext.Initialize(1, mcuContext);
// Get the modality-specific MCU's available for conference.
this.myConfManagerSession.GetAvailableMcuList(mcuOperationContext);
/*
* the conference schedule functionality should be done when a list of available
* MCUs has been returned.
*/
// Create the conference information object and fill properties to describe conference.
UccConferenceInformation confInfo = this.CreateConferenceInfo(
"Test Conference",
UCC_CONFERENCE_ADMISSION_TYPE.UCCCAT_OPEN_AUTHENTICATED);
UccOperationContext scheduleOperationContext = new UccOperationContextClass();
UccContext scheduleContext = new UccContextClass();
scheduleContext.AddNamedProperty("ScheduleConference", true);
scheduleOperationContext.Initialize(1, scheduleContext);
// Create the conference on the Focus server.
this.myConfManagerSession.ScheduleConference(
confInfo,
scheduleOperationContext);
return;
}
After a local client has scheduled a conference and received the OnScheduleConference event and the IUccOperationProgressEvent parameter indicates no error on scheduling, the new conference can be joined. For information about joining a conference, see Joining and Leaving Conferences.
Handling conference events
Although the conference manager session can raise six different events, the two events described in the following sections must be handled when a local client schedules a new conference.
OnScheduleConference
The client receives a OnScheduleConference event when a Focus Factory has processed the request to schedule a conference. The callback method that handles this event is a good place to initiate the remote user invitation process. The remote user invitation process is discussed in the Invite Users to a Conference topic.
/// <summary>
/// Raised when a Focus Factory has processed a request to create a conference
/// </summary>
/// <param name="pEventSource"></param>
/// <param name="pEventData"></param>
void _IUccConferenceManagerSessionEvents.OnScheduleConference(
UccConferenceManagerSession pEventSource,
IUccOperationProgressEvent pEventData)
{
// Was conference scheduled on Focus Factory?
if (pEventData.StatusCode >= 0)
{
// The conference Id and conference URI are contained in the
// original operation context. These properties are filled by the
// Focus Factory and returned to the client in this event.
IUccProperty p = null;
// Get operation context object sent by Focus Factory.
UccOperationContext oc = pEventData.OriginalOperationContext;
p = null;
// Get operation context named property for conference Id.
string confId = string.Empty;
if (oc.Context.IsNamedPropertySet("ConferenceID"))
{
p = oc.Context.get_NamedProperty("ConferenceID");
if (p != null)
confId = p.StringValue;
}
p = null;
// Get conference Focus URI.
int propEnum = (int)UCC_CONFERENCE_MANAGER_OPERATION_COMPLETED_EVENT_PROPERTY
.UCCCMOCEP_CONFERENCE_URI;
p = pEventData.Properties.get_Property(propEnum);
if (p != null)
{
MessageBox.Show("Conference Focus URI: " + p.StringValue);
}
}
}
To review an example that handles OnScheduleConference, see Conference Manager Sessions.
OnGetAvailableMcuList
This event returns the MCUs supported on a conference Focus. Before configuring a new conference, a local client must handle this event if the conference is to be correctly configured.
/// <summary>
/// Handles the event raised when the client platform has received a list of
/// supported MCUs from a conference Focus Factory
/// </summary>
/// <param name="pEventSource">UccConferenceManagerSession conference manager session requesting the MCU list</param>
/// <param name="pEventData">IUccOperationProgressEvent event data containing the returned MCU list</param>
void _IUccConferenceManagerSessionEvents.OnGetAvailableMcuList(
UccConferenceManagerSession pEventSource,
IUccOperationProgressEvent pEventData)
{
if (pEventData.IsComplete == true && pEventData.StatusCode >= 0)
{
UccContext opContext = pEventData.OriginalOperationContext.Context;
IUccReadOnlyPropertyCollection mcuCollection = pEventData.Properties;
IUccProperty availableMCUs = mcuCollection.get_Property(
(int)UCC_CONFERENCE_MANAGER_OPERATION_COMPLETED_EVENT_PROPERTY.UCCCMOCEP_AVAILABLE_MCUS);
IUccCollection convView = availableMCUs.Value as IUccCollection;
if (convView != null && convView.Count > 0)
{
foreach (IUccProperty MCU in convView)
{
UCC_CONFERENCE_ENTITY_TYPE mcuTYPE = (UCC_CONFERENCE_ENTITY_TYPE)MCU.NumericValue;
MessageBox.Show("MCU supported: " + mcuTYPE.ToString());
}
}
}
}
See Also
Concepts
Conference Manager Sessions
Conferencing Class: Code Listing