Share via

Programming Patterns with Conference Scheduling Objects

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

Programming with a conference management object involves making a call into a method on a conference management interface and handling asynchronous responses with application callback functions. An advantage of an asynchronous method is that your code is not blocked while waiting for a response from the remote server. Your callback function is called by the Unified Communications Client API assembly, allowing your code to avoid being blocked.

The interface methods of the conference management object are essentially requests on the Focus Factory component of Office Communications Server for information. That requested information might be a list of scheduled conferences, an individual conference information object, or a list of available multipoint control units (MCUs). Another type of request on the Focus Factory component is an operational request to create, change, or terminate a conference.

A typical conference management session event you handle is an event raised to confirm the completion of a requested operation. For example, the request to terminate a conference raises an OnDeleteConference event. The event argument contains properties that indicate success or failure. In the case of a failed request, the event provides a status code and status reason for the failure. A status code greater than or equal to zero value indicates the request succeeded.

Unified Communications Client API provides a mechanism for you to associate a method call with the corresponding event raised. The IUccOperationContext interface is optionally passed as an argument to each request. This interface provides you with a space to pass context data to the callback function event handler. This context data allows the code in your callback function to provide better functionality.

The conferences that can be listed, changed, or terminated are limited to those conferences that the local user has scheduled. It is not possible to perform this functionality on conferences that a different user has scheduled.

The general programming patterns when working with conference management objects are as follows:

  1. If using C++, call QueryInterface on an endpoint to get an IUccConferenceManager interface. Using a .NET language such as C#, cast the endpoint interface to IUccConferenceManager.
  2. Use the resulting interface to create an IUccConferenceManagerSession interface.
  3. Advise for the events raised by the conference manager session interface. The class you create to do this must implement the callback functions specified by the _IUccConferenceManagerSessionEvents interface.

After completing these steps, complete the following tasks.

Get Available MCUs

This task should be done before a conference is created or configured. A central aspect of conference configuration is specifying the media type used in the conference. The new conference might be a telephone-only conference or an audio/video conference. A conference can only be configured for the MCUs supported by the Focus Factory. You do not have to configure a conference to use all the available media modalities represented by the set of MCU components. For an example of this task, see Schedule a Conference

The following pattern is a good way to accomplish this task:

  1. If you want to supply application-specific context data with the method call, you must instantiate and initialize a co-creatable operation context object, UccOperationContext. The operation context object is passed to the Focus Factory component and returned to your application in the corresponding event raised when the operation is complete.
  2. Call into the GetAvailableMcuList method on the IUccConferenceManagerSession interface, optionally passing an operation context object.
  3. In the callback handler OnGetAvailableMcuList, cast the Properties property to the IUccReadOnlyPropertyCollection interface.
  4. Call into the get_Property method of the interface, passing the enumeration UCC_CONFERENCE_MANAGER_OPERATION_COMPLETED_EVENT_PROPERTY.UCCCMOCEP_AVAILABLE_MCUS. A IUccProperty interface pointer is returned.
  5. The returned IUccProperty should be cast into the IUccCollection interface. The collection can now be iterated to get the individual MCU properties. The individual collection items should be cast to the IUccProperty interface so you can read the NumericValue property.
  6. Compare each numeric value to the UCC_CONFERENCE_ENTITY_TYPE enumeration to determine the type of MCU returned.
  7. If you passed an operation context object with the request method, that context is available by reading the OriginalOperationContext property of the IUccOperationProgressEvent object.

Create a Conference

Creating a conference involves creating an IUccConferenceInformation object to configure a conference and passing that conference information object as an argument to the ScheduleConference method.

To schedule a conference, follow this pattern:

  1. Use the IUccConferenceManagerSession object to create an IUccConferenceInformation object by calling the CreateConferenceInformation method.
  2. Obtain the property collection object of the IUccConferenceInformation object by reading the Properties property. This property returns an IUccPropertyCollection object.
  3. The obtained property collection is initially empty but you can add properties representing the set of conference configuration values from the UCC_CONFERENCE_INFORMATION_PROPERTY enumeration. To add a configuration value, call the AddProperty method on the IUccPropertyCollection interface where the integer parameter is an enumeration value and the object parameter is the value of the conference configuration you want to set. All the conference configuration parameters are optional but you should set the admission type, subject, expiration date, admission key, and MCUs. The MCU types you set must be in the list of supported MCUs you received from the OnGetAvailableMcuList event.
  4. You can optionally add an operation context to the conference scheduling request. Do this if you want your application to match scheduling requests made with resultant OnScheduleConference events. For example, you can give each conference you schedule a unique application-generated identifier and a topic string. As you handle the OnScheduleConference event using your callback function, you can examine the operation context object returned with the event to match it to the corresponding scheduling request. Adding an operation context to the scheduling request is done with the following pattern:
    • Create a co-creatable UccOperationContext object.
    • Using your platform object, create an IUccContext object by calling the CreateEndpoint method on the platform object.
    • Using the context object you just created, call AddNamedProperty, if you create the property with a string key. Creating the property with an integer key requires that you call AddProperty. One of the properties you create should indicate the nature of the request operation. In this case, the request operation schedules a conference.
    • Call the Initialize method on your operation context object.
  5. Call the ScheduleConference method on the conference manager session object. If you created an operation context, pass that object as the second argument of the function.
  6. In your OnScheduleConference callback function, examine the StatusCode property of the returned EventData argument. This property returns an integer value that must be greater or equal to zero to indicate success. If you provided the request operation type with the operation context object when you made the request, your callback function can execute code steps appropriate for the request. In this case, the callback function should retrieve the conference URI. When you create a conference session and enter the conference, this URI is required. The Initialize method of the conference session interface accepts the conference URI as the first argument. For more information, see Joining and Leaving Conferences.

Configure a Conference

A conference can be configured when you schedule it. It can also be configured or reconfigured after you have scheduled the conference on the server. This is often the case when you do not have a complete list of potential attendees or you want to add a media type to the collection of MCUs you configured when you scheduled the conference. You have access to the full set of configuration values that were available when the conference was originally scheduled.

To configure a conference, you must request the IUccConferenceInformation object for the conference in question. To do this, provide the conference ID of the desired conference. You can obtain this by first requesting a list of unexpired conferences you previously scheduled. The following programming pattern illustrates a typical conference reconfiguration scenario:

  1. Make an GetConferenceList request. You should provide an operation context if your application users are likely to concurrently configure conferences. The provided operation context allows your application to match an operational request with the corresponding event response. It is a good idea to indicate that this request is the basis of a conference configuration request. You can create a name/value property pair in the operation context object for this purpose. This provides the callback function event handler for OnGetConferenceList with the information required to determine what further action is necessary. In this case, your callback function can complete the configuration.
  2. Using your OnGetConferenceList callback method, find the interested conference in the collection of active conferences returned with the event.
  3. With the conference ID of the interested conference, call the GetConference method, passing the conference ID as the first parameter. As with the GetConferenceList request, you should include an operational context object as the second parameter to this method call.
  4. Using your OnGetConference callback method, get the IUccConferenceInformation object from the EventData argument of the method. Be sure to examine the properties of the returned operation progress event to match this event with the corresponding request.
  5. Update the properties of the conference information object as was done when the conference was scheduled.
  6. Optionally, you can create a IUccOperationContext object that allows you to match the resultant event to this ModifyConference request. Your callback method that handles the OnModifyConference event can read the operation context properties you set with the request. If your operation context included a unique identifier for the conference modification request, the callback function can match the request to the event response.
  7. Call the ModifyConference method, passing the conference information object just updated and the optional operation context object. Because the conference information object includes a conference ID, you do not need to identify the conference you are updating.
  8. To verify that the modification of the conference configuration is stored successfully on the Focus Factory component, your application should handle the OnModifyConference event with a callback function for that purpose. The IsComplete Boolean property returns a True value if the operation completed. A False value indicates the operation did not complete. The StatusCode indicates a completed operation is successful when its integer value is not negative. The StatusText property is a string that contains a failure reason when an operation fails.

Terminate a Conference

As with the conference configuration task, canceling a conference requires that you provide a conference ID in the DeleteConference request. You can obtain a list of your active conferences eligible for deletion by calling into the GetConferenceList method.

The following programming pattern illustrates a typical conference deletion scenario:

  1. Make a GetConferenceList request. You should provide an operation context if your application users are likely to concurrently delete conferences. The provided operation context allows your application to match operational request with the corresponding event response. As with other operational requests, you should use the operational context object to communicate the operation request type to your GetConferenceList callback method.
  2. Using your OnGetConferenceList callback method, find the interested conference in the collection of active conferences returned with the event. If you have supplied the operation request type in the operation context object, your callback function can trigger the conference deletion functionality.
  3. The callback function you provide to handle the OnDeleteConference event can examine the StatusCode property of the IUccOperationProgressEvent object to determine the success of the delete request.

See Also

Concepts

Conference Manager Creation
Conference Manager Session Object