Configuring a Client Computer for Cross-Firewall Media Connectivity
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.
Configuring a client computer for cross-firewall media collaboration involves:
- Setting a media stack port range restriction on the endpoint.
- Adding media connectivity servers to the endpoint.
The media endpoint settings interface is obtained by a cast from an endpoint object. The endpoint object is responsible for handling communications with media connectivity servers in an audio/video session and other remote endpoints. Although you can add a media connectivity server to an un-enabled endpoint, it is better to do so in the OnEnable callback event handler. For a general discussion about the programming patterns with media connectivity objects, see Programming Patterns with Media Connectivity Objects.
Set a Port Range
The following example illustrates using the IUccMediaEndpointSettings interface to set a port range limiting the ports available to the media manager for audio and video. This is usually done when the local workstation running a Unified Communication Client API implementation application has IP security configured and running. IP security sets aside a range of ports where security is not applied. This port range that the code implemented must be used by the media manager.
Note
If a single media relay server is configured for multiple protocols, each media connectivity server configured for the media endpoint at that Address must use the same Priority.
To restrict the media stack to a range of computer ports, call SetMediaPortRange on the media endpoint settings interface as shown in the following example.
_mediaEndpointSettings = (IUccMediaEndpointSettings)_endpoint;
short s_lowPort = 1020;
short s_highPort = 1040;
try
{
if (s_lowPort >= 1000 && s_highPort >= (s_lowPort+20))
{
_mediaEndpointSettings.SetMediaPortRange(s_lowPort, s_highPort);
}
}
catch (COMException e)
{
//exception code;
}
Setting a port range for computer ports reserved by other processes results in a COM exception. Generally, port numbers greater than 1000 are not reserved by an operating system. To avoid the processing cost of raising an exception, validate the requested port range before attempting to set the range. A client can carry on multiple A/V sessions concurrently, each session using ports in the range set aside for the media stack. The minimum requirements for audio + video sessions are four ports. The example ensures that a range of 20 ports are available to prevent the possible failure of an A/V session due to lack of available ports.
Add a Media Connectivity Server
The following example uses the media relay server address and port values cached on a local computer. This method allows you to add a single media connectivity server at a time. However, you must supply all the configuration arguments from a local cache. If a media connectivity server is added to a topology or reconfigured, you must update the configuration stored locally.
if (_endpointEnabled)
{
_mediaConnectivitySvr = _mediaEndpointSettings.AddMediaConnectivityServer(
UCC_MEDIA_CONNECTIVITY_SERVER_TYPE
.UCCMCST_HTTP_PROXY, //server type
szServerAddress, //server address
lPort, //server port
_transportMode, //transport mode
"*", //realm
1); //priority
}
Find Media Connectivity Servers
A good way to avoid the necessity of a locally stored configuration is to get the configuration information from a server on the organization topology when an endpoint is enabled. Unified Communications Client API provides a method to find media connectivity servers in an organization topology by making a single call into the FindMediaConnectivityServers method. In the following example, the code uses a literal string to represent the Uri of the MRAS server that provides the search results. Normally, you subscribe to the serverConfiguration category and receive the MRAS Uri string from the MediaRelayAuthenticationServerUri property of the strongly typed category, IUccServerConfigurationCategory.
The following programming pattern is used in this example code:
- Obtain a media settings interface from an enabled endpoint.
- Advise the endpoint object of the implemented media endpoint settings callback functions.
- Call into FindMediaConnectivityServers and pass the MRAS Uri. Optionally, you can pass an IUccContext object.
IUccMediaEndpointSettings _mediaEndpointSettings = (IUccMediaEndpointSettings)_endpoint;
UCC_Advise<_IUccMediaEndpointEvents>(_endpoint, this);
string _MRASUri = "sip:MRASLoc.contoso.com@contoso.com;gruu;opaque=srvr:MRAS:bMOjOHEFQiCtPh2g624vPAAA";
_mediaEndpointSettings.FindMediaConnectivityServers(this._MRASUri, null);
Handle OnFindMediaConnectivityServers Event
The MRAS server responds to the call to FindMediaConnectivityServers with a collection of media connectivity servers. An organization can use any number of media connectivity servers. It is best to add all returned servers to the media endpoint settings object. Using AddMediaConnectivityServerWithCredential, you do not specify any of the server configuration values required with the previous example.
void _IUccMediaEndpointEvents.OnFindMediaConnectivityServers(
IUccMediaEndpointSettings pEventSource,
IUccFindMediaConnectivityServersEvent pEventData)
{
if (OnFindMediaConnectivityServer != null)
{
IUccCollection serverConfig = pEventData.MediaConnectivityServerConfigurations;
foreach (IUccMediaConnectivityServerConfiguration m in serverConfig)
{
_mediaEndpointSettings.AddMediaConnectivityServerWithCredential(m);
}
}
}