This documentation is archived and is not being maintained.

Creating a Connection Manager

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 create the following connection managers, depending on its role as a client or a server (including a middle-tier application):

  • Client connection manager for either TCP or TLS. A client connection manager is used by a Unified Communications Managed API version 1.0 application that functions as a client and does not listen to incoming connections.
  • Server connection manager using TCP, TLS, or mutual TLS (MTLS). For descriptions of these transport types, see Terminology (Unified Communications Managed API version 1.0). A server connection manager is used as a Unified Communications Managed API version 1.0 application that functions as a server with an ability to listen to incoming connections.

The following code example illustrates the programming pattern for creating a client connection manager.

RealTimeClientConnectionManager connectionManager = new RealTimeClientConnectionManager();

A client connection manager is used for a client that does not normally have a certificate for authentication with a server.

Applications that must receive notifications whenever a connection pool (which is used for outgoing connections) is added to or removed from the connection manager can subscribe to the ConnectionPoolAdded or ConnectionPoolRemoved events after the connection manager is created. The first two statements in the following code example register handlers for the ConnectionPoolAdded and ConnectionPoolRemoved events. The method definitions in this example are skeletons for the handlers for the two events.

connectionManager.ConnectionPoolAdded += connectionManager_ConnectionPoolAdded);

connectionManager.ConnectionPoolRemoved += connectionManager_ConnectionPoolRemoved);

void connectionManager_ConnectionPoolAdded(object sender, 
                       CollectionChangedEventArgs<ConnectionPool> e)
{
  // Handle the ConnectionPoolAdded event.
}

void connectionManager_ConnectionPoolRemoved(object sender, 
                       CollectionChangedEventArgs<ConnectionPool> e)
{
  // Handle the ConnectionPoolRemoved event.
}

A server connection manager is represented by a RealTimeServerConnectionManager object. Depending on the transport type used, a server connection manager can be of the RealTimeServerTcpConnectionManager or RealTimeServerTlsConnectionManager type. Different subclasses encapsulate different functionalities dictated by the chosen transport.

The following code example is a programming pattern for creating a RealTimeTcpServerConnectionManager instance. If IsListening on the server connection manager is false, StartListening is called, enabling the server connection manager to listen for client activity on all network interfaces and on any available port.

RealTimeServerTcpConnectionManager serverConnectionManager = new RealTimeServerTcpConnectionManager();
if (!serverConnectionManager.IsListening)
{
  serverConnectionManager.StartListening(
                               new IPEndPoint(IPAddress.Any, 0));
}

In addition to ConnectionPoolAdded and ConnectionPoolRemoved events, an application can choose to subscribe to the IncomingConnectionAdded, IncomingConnectionRemoved, or ListeningAddressesChanged event and other events specific to a server connection manager. The following C# code excerpt illustrates the programming pattern for subscribing to the IncomingConnectionAdded event. The first statement registers a handler for the IncomingConnectionAdded event. The method definition shows a skeleton of the handler for this event.

serverConnectionManager.IncomingConnectionAdded += serverConnectionManager_IncomingConnectionAdded);

void serverConnectionManager_IncomingConnectionAdded(object sender, IncomingConnectionAddedEventArgs e)
{
  // Handle an IncomingConnectionAdded event
}

A server TLS connection manager requires a certificate installed locally. For more information, see the Microsoft Office Communications Server 2007 Administration Guide topics "Configuring Certificates for Servers" and "Configuring Internal and External Interfaces and Certificates for Edge Servers." Also see Related Links (Advanced Certificate Enrollment and Management). The connection manager presents this certificate to a remote application that initiated the incoming connection. The remote application uses this certificate to ascertain the security level of this server-like application. Thus, the RealTimeServerTlsConnectionManager class constructors require the input of the issuer name and the serial number of the certificate. The following code example, taken from the BroadcastIM sample, demonstrates the use of one of the constructors for this class.

string m_IssuerName = ...; // Get name of certificate issuer
byte[] m_SerialNumber = ...; // Get certificate serial number
RealTimeServerTlsConnectionManager serverTlsConnectionManager;
try
{
  serverTlsConnectionManager = new RealTimeServerTlsConnectionManager(m_IssuerName, m_SerialNumber);
}
catch (TlsFailureException)
{
  MessageBox.Show("Cannot retrieve the X.509 certificate.");
  return;
}
Show: