CollaborationPlatform

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 CollaborationPlatform class provides connection management, message dispatching, and other services to endpoints. An application creates an instance of the CollaborationPlatform class to take advantage of the Unified Communications Managed API 2.0 Core SDK infrastructure. An application developer can use one of the constructors in this class to create a server platform, from which an application server can be created. An application developer can use another constructor in this class to create a client platform, on which a number of user endpoints can be created.

The following topic describes the settings parameters used in the CollaborationPlatform constructors.

• CollaborationPlatformSettings and Subclasses

Client Platforms and Server Platforms

A client platform typically is used to support the creation of a large number of clients that can be used to simulate users connected to an application, for the purpose of carrying out stress and scalability testing on an implementation of an application server. A different application can create a server platform that targets Office Communications Server 2007 R2. A server platform can be used with both UserEndpoint and ApplicationEndpoint instances. Before creating the endpoint, an application should start the platform. When the application server shuts down, it can terminate all endpoints and shut down the platform.

Proper Platform Shutdown

If a CollaborationPlatform instance that is not shut down correctly can result in a memory leak, because unmanaged-code media stack resources might not be released. For a CollaborationPlatform instance to be shut down properly, an application must call BeginShutdown() and EndShutdown(). The following code example shows how these methods can be used to initialize and uninitialize the CollaborationPlatform instance.

private void Initialize()
{
  bool needCleanup = true;
  try
  {
    myPlatform = new CollaborationPlatform(new ClientPlatformSettings(userAgent, SipTransportType.Tls));
    myPlatform.BeginStartup(this.PlatformStartupCompleted, myPlatform);
    needCleanup = false;
  }
  catch (InvalidOperationException)
  {
           // Handle invalid operation exception.
  }
  finally 
  {
    if(needCleanup) 
    {
    // Handle cleanup.
    }
  }
}

private void PlatformStartupCompleted(IAsyncResult asyncResult) 
{
  bool needCleanup = true;
  try
  {
    CollaborationPlatform platform = asyncResult.State as CollaborationPlatform;
    platform.EndStartup(asyncResult);

    //platform successfully started up. Proceed with next steps.
  }
  catch (OperationFailureException)
  {
    // Handle operation failure exception.
  }
  catch (ConnectionFailureException) 
  {
    // Handle connection failure exception.
  }
  catch (RealTimeException) 
  { 
    // Handle RealTime exception. 
  }
  finally
  { 
    if(needCleanup) 
    {
      // Handle cleanup.
    }
  }
}



private void Uninitialize()
{
  // Other clean-up operations...

  if (myPlatform != null)
  {
    myPlatform.BeginShutdown(this.PlatformShutdownCompleted, myPlatform));
  }
}


private void PlatformShutdownCompleted(IAsyncResult asyncResult) 
{
  CollaborationPlatform platform = asyncResult.State as CollaborationPlatform;
  platform.EndShutdown(asyncResult); 
  // EndShutdown will not throw RealTimeException or any subclass.
}

CollaborationPlatform Constructors

The CollaborationPlatform class can be instantiated as a server platform or as a client platform.

// Creates a new instance of the CollaborationPlatform class as a server platform.
public CollaborationPlatform(ServerPlatformSettings platformSettings);

// Creates a new instance of the CollaborationPlatform class as a client platform.
CollaborationPlatform(ClientPlatformSettings platformSettings);

CollaborationPlatform Properties

Some public properties of the CollaborationPlatform class appear in the following example.

// Gets the local host used for the platform.
public string LocalHost {get;}

// Gets the application user agent string.
// This is used to build the overall UserAgent string for each endpoint.
public string ApplicationUserAgent {get;}

// Gets the transport type to use.
// The default transport type is TLS.
public SipTransportType Transport {get;}

// Gets the GRUU of the application.
// The GRUU is used automatically for privileged
// commands for applications that require it. on the server.
// The value is valid only when using a server-model platform with
// an ApplicationEndpoint, otherwise the string is empty.
public string ActiveGruu {get;}

// Gets the IP address on which the platform will listen.
public IPAddress ListeningIPAddress {get;}

// Gets the active listening endpoint in use. 
public IPEndPoint ActiveListeningIPEndpoint {get;}

// Gets the connection manager used by the platform. 
// This property can be used for advanced scenarios,
// such as setting connection pool size or message throttling limits.
public RealTimeConnectionManager ConnectionManager {get;}

// Gets or sets the authentication protocol to be used for user endpoints.
public SipAuthenticationProtocols AllowedAuthenticationProtocol {get; set;}

// Gets or sets global configuration settings for InstantMessagingFlow.
public InstantMessagingFlowTemplate InstantMessagingSettings {get; set;}

// Gets audio and video settings.
public AudioVideo.AudioVideoSettings AudioVideoSettings {get;}

// Gets whether audio and video platform capabilities are enabled.
public bool DefaultAudioVideoProviderEnabled {get;}

Descriptions of frequently-used properties of the CollaborationPlatform class appear in the following table.

ApplicationUserAgent

The user agent that represents the application. This is set by the application on the ServerPlatformSettings or ClientPlatformSettings object and is used to construct the UserAgent string.

Transport

The transport type used to set up connections. For a client platform the value is set explicitly by the constructor; for a server platform the value depends on whether a certificate has been set. If a certficate has been set, the Transport value is Tls; otherwise it is Tcp. For security reasons, we recommend that you use Transport Layer Security (TLS) or Mutual Transport Layer Security (MTLS) rather than Transmission Control Protocol (TCP).

CollaborationPlatform Methods

Some public methods of the CollaborationPlatform class appear in the following example.

// Dynamically changes the certificate to be used. 
// The platform must stop listening,
// change the certificate, and then start listening again.
// Although this method does not affect existing connections,
// the application should expect a possible temporary disruption
// in new incoming connections.
public IAsyncResult BeginChangeCertificate(
    X509Certificate2 certificate,
    AsyncCallback userCallback,
    object state);

// Dynamically changes the certificate to be used. 
// Although this method does not affect existing connections,
// the application should expect a possible temporary disruption
// in new incoming connections.
public IAsyncResult BeginChangeCertificate(
    string certificateIssuerName,
    byte[] certificateSerialNumber, 
    AsyncCallback userCallback, object state);

// Completes the operation started by BeginChangeCertificate
public void EndChangeCertificate(IAsyncResult result);

// Initializes the platform object.
public IAsyncResult BeginStartup(AsyncCallback userCallback, object state);

// Returns the results from the start operation.
public void EndStartup(IAsyncResult result);

// Shuts down the platform and all known endpoints.
public IAsyncResult BeginShutdown(AsyncCallback userCallback, object state);

// Gets the results from the shutdown operation
public void EndShutdown(IAsyncResult result);

// Registers an extension with the platform.
// Extensions such as call factories that support specific media types can be registered only
// if there is no existing extension for the media type. 
public void RegisterPlatformExtension(MediaBasedFactory extension);

// Unregisters the extension.
public MediaBasedFactory UnregisterPlatformExtension(string extensionType, string mediaType);

After creating the platform object, the BeginStartup() method must be called before the platform is used to create endpoints. If a server platform is created, the underlying connection manager begins listening on the configured port.

The BeginShutdown() method disconnects all connections, terminates all the endpoints, and stops listening on its port. The platform cannot be used for any communications after it is shut down.