About This Release

Article
05/23/2014

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.

Applying KB982170 or using Microsoft Unified Communications Managed API 2.0 Core SDK containing UcmaRedist.msi with a build number greater than 3.5.6907.170 differs from the previously released version of the UCMA SDK. These differences are shown in this document.

Support for the deployment of 64-bit UCMA applications

64-bit UCMA 2.0 Core applications can now be deployed on Microsoft Windows Vista SP1 (64-bit Editions) and higher and Microsoft Windows 7 (64-bit Editions).

Introduction of the default routing ApplicationEndpoint

The default routing endpoint enables an application to process incoming SIP requests that are received by a CollaborationPlatform instance, that are not promptly dispatched to another ApplicationEndpoint on the same CollaborationPlatform, based on the ApplicationEndpoint owner or Conversation information matching the incoming request. Instead of being automatically declined by the CollaborationPlatform, such a received request is raised on the default routing ApplicationEndpoint, when one exists. This enables an application to process these requests.

Note that there can be at most one ApplicationEndpoint that is marked as the default routing endpoint for a given CollaborationPlatform instance.

Typical usage: Instead of hanging up when a call is routed to a decommissioned service, an application has an opportunity to play an announcement back to the caller. Also, when used as the unique ApplicationEndpoint for the platform, the default routing endpoint is ideal for creating services that concurrently interoperate with remote SIP peers such as Microsoft Office Communications Server 2007 R2 or selected other IP-PBXs and SIP PSTN Gateways.

New API:

public class ApplicationEndpoint : LocalEndpoint {
    public Boolean IsDefaultRoutingEndpoint { get; }
    public void SetProxyInformation(String proxyHost, Int32 proxyPort);
}

public class ApplicationEndpointSettings : LocalEndpointSettings {
    public Boolean IsDefaultRoutingEndpoint { get; set; }
}

Introduction of support for SIP DNS load balancing

UCMA 2.0 Core SDK is now capable of load balancing outbound SIP requests to a next-hop proxy with multiple front ends using DNS A records. Note that this QFE does not support DNS load balancing for ICE connectivity check failover. A Microsoft Office Communications Server AudioVideoEdgeServer must still be fronted by a Hardware Load Balancer.

New API:

public abstract class RealTimeConnectionManager : IDisposable {
    public Boolean DnsLoadBalancingDisabled { get; set; }
}

From a LocalEndpoint implementation the DnsLoadBalancingDisabled property can be accessed as in the following example.

endpoint.InnerEndpoint.ConnectionManager.DnsLoadBalancingDisabled = false;

Introduction of a platform interoperability mode with SIP PSTN gateways and IP-PBXs for telephony scenarios

UCMA 2.0 Core SDK now provides first-class APIs to override the endpoint next-hop proxy on an AudioVideoCall establishment basis. This enables an application to operate in SIP Peer-To-Peer mode with multiple SIP PSTN Gateways and IP-PBXs at the same time.

New API:

This QFE introduces a new ConnectionContext API that can be applied to outbound SIP Requests (page mode requests or calls).

public class ApplicationEndpointSettings : LocalEndpointSettings {
    public ConnectionContext AudioVideoAuthorizationService { get; set; }
}

public class CallEstablishOptions {
    public ConnectionContext ConnectionContext { get; set; }
    public String Transferor { get; set; }
}
public abstract class RealTimeEndpoint {
    public IAsyncResult BeginSendMessage(
                               MessageType messageType,
                               RealTimeAddress sessionTarget,
                               SendMessageOptions options,
                               AsyncCallback userCallback,
                               Object state);
    }

public class SendMessageOptions {
    public ConnectionContext ConnectionContext { get; set; }    
    public void SetLocalIdentity(String uri, String displayName);
}

public class SignalingSession {
    public IAsyncResult BeginEstablish(SignalingSessionEstablishOptions options, AsyncCallback userCallback, Object state);
}

public class SignalingSessionEstablishOptions {
    public ConnectionContext ConnectionContext { get; set; } 
}

UCMA 2.0 Core SDK also provides an API that can be used to authorize or decline an incoming connection manually, retrieve configuration data pertaining to a specific remote SIP Peer, and to persist this information in the associated RealTimeConnection.ApplicationContext prior to the AudioVideoCall reception being raised to the application.

New API:

public abstract class RealTimeServerConnectionManager : RealTimeConnectionManager, IDisposable {
    public event EventHandler<ConnectionAuthorizationRequestedEventArgs> ConnectionAuthorizationRequested;
}

public class ConnectionAuthorizationRequestedEventArgs : EventArgs {
    public ConnectionAuthorizationAction Action { get; }
    public RealTimeConnection Connection { get; }

    public void Allow();
    public void DelayAuthorization();
    public void Deny();
}

public class ConnectionContext {
    public ConnectionContext(String host, Int32 port);

    public Int32 Port { get; }
    public String Host { get; }
}

A server TCP CollaborationPlatform is configured to enable voice interoperability with remote SIP peers and IP-PBXs. Note that Microsoft Office Communications Server 2007 R2 does not support trusted services using TCP.

A server MTLS CollaborationPlatform is configured to enable interoperability with Microsoft Office Communications Server 2007 R2 proxies and endpoints. For interoperability with remote SIP peers of other types, such as IP-PBXs or SIP PSTN Gateways, the new TrustedDomain class enables an application to specify arbitrary remote SIP peers.

New API:

public class CollaborationPlatform {
    public Boolean AddTrustedDomain(TrustedDomain trustedDomainEntry);
    public ReadOnlyCollection<TrustedDomain> GetTrustedDomains();
    public Boolean RemoveTrustedDomain(TrustedDomain trustedDomainEntry);

    public event EventHandler<ConnectionAuthorizationRequestedEventArgs> ConnectionAuthorizationRequested;
}

public class ServerPlatformSettings : CollaborationPlatformSettings {
    public Collection<TrustedDomain> TrustedDomains { get; }
    public TrustedDomainMode TrustedDomainModeForTcp { get; set; }
}

public class TrustedDomain {
    public TrustedDomain(String domainName);
    public TrustedDomain(String domainName, TrustedDomainMode domainMode);

    public String DomainName { get; }
    public TrustedDomainMode DomainMode { get; }
}

public enum TrustedDomainMode {
    CommunicationsServer,
    Other
}

Here are some of the details of the interoperability mode with remote SIP peers other than Microsoft Office Communications Server 2007 R2.

ICE draft v6.0 and draft v19.0 support is disabled.
All “ms-” headers other than “ms-diagnostic” are filtered out of a message.
Quality of Experience (QoE) metrics are not published to the remote SIP peers but are consistently raised to the application when available.
Support for SDP-less INVITE and re-INVITE has been added, providing interoperability with third-party call controllers.

Support for diversion

This QFE enables application writers to find the first or last diversion prior to receiving an incoming call.

New API:

CallReceivedEventArgs is derived from the abstract CallReceivedEventArgsBase class, which in turn is derived from the InviteReceivedEventArgs class, hence CallReceivedEventArgs exposes the same API as InviteReceivedEventArgs.

public class CallReceivedEventArgs<TCall> : CallReceivedEventARgsBase where TCall: Call {
    public TCall Call {get;}
    public TCall CallToBeReplaced {get;}
}

public abstract class InviteReceivedEventArgs : SipRequestReceivedEventArgs {
    public DiversionContext DiversionContext { get; }
}

Enhanced call setup failure diagnostics and Quality of Experience

Quality of Experience metrics are raised to the application upon terminating an AudioVideoCall in which an AudioVideoFlow was successfully established. The information pertaining to the Quality metrics is described in the following MSDN topic: http://msdn.microsoft.com/en-us/library/dd905463.aspx.

An application developer can also monitor whether the media session was successfully established upon termination of an established AudioVideoCall. For failed media sessions, the developer can query diagnostic information pertinent to the media session failure in order to help logging and troubleshooting of connectivity issues with remote users.

New API:

public class AudioVideoCall : Call {
    public event EventHandler<MediaTroubleshootingDataReportedEventArgs> MediaTroubleshootingDataReported;
}

public class MediaChannelEstablishmentData {
    public MediaChannelEstablishmentStatus EstablishmentStatus { get; }

    public MediaChannelEstablishmentDiagnosticsReason GetDiagnosticsReason();
}

public enum MediaChannelEstablishmentDiagnosticsReason {
    Unknown,
    MediaEdgeAuthenticationServiceDiscoveryFailed,
    MediaEdgeAuthenticationServiceCredentialsAcquisitionFailed,
    MediaEdgeResourceAllocationFailed
}

public class MediaTroubleshootingDataReportedEventArgs : EventArgs {
    public Collection<MediaChannelEstablishmentData> MediaChannelEstablishmentDataCollection { get; }
    public ContentDescription QualityOfExperienceContent { get; }
}

Support for sampling rate for both stream directions

This feature enables an application to specify the sampling rate in either stream direction (Send/Receive).

New API:

public AudioSamplingRate AudioChannelTemplate.ReceiveDirectionSamplingRate {get; set;}
public AudioSamplingRate AudioChannelTemplate.SendDirectionSamplingRate {get; set;}

public AudioSamplingRate AudioChannel.SendDirectionSamplingRate {get;}
public AudioSamplingRate AudioChannel.ReceiveDirectionSamplingRate {get;}

Support for in-band fax tone detection (CNG 1100Hz)

This feature enables an application to detect when a fax tone is received from a remote peer. If the application has subscribed to the IncomingFaxDetected event on the ToneController class, it can detect an incoming fax tone in either of the following situations.

in-band fax tone (CNG tone event in the RTP stream sent according to RFC 2833)
out-of-band fax tone (CNG tone is sent over the RTP event)

New API:

public class IncomingFaxDetectedEventArgs : EventArgs {
}

public event EventHandler<IncomingingFaxDetectedEventArgs> IncomingFaxDetected

Support for Player playback speed

This feature enables an application to use a new property on the Player class to provide the capability to play back the WMA file at a different speed. An application can use the PlaybackSpeed property to develop an interface that gives the user more control in consuming the content. A message can be played back faster or slower depending on the PlaybackSpeed that the application specifies.

New API:

public PlaybackSpeed PlaybackSpeed {get; set;}

The PlaybackSpeed enumeration members range from Half (half the normal speed) to TwoTimes (twice the normal speed).

Improved Recorder

Several new APIs are introduced in this QFE in the Recorder class to allow more complex scenarios to be developed.

An application can now use the Pause method to pause recording during a recording session. An application can use the Start method to resume recording from where the file was paused. Note that Start starts recording from the beginning of the file if the Stop method previously was called.

New API:

public void Pause();

A new enumeration value, Paused, has been added to the RecorderState enumerated type.

An application can now use the VoiceActivityChanged event to detect that the content is voice or not voice. With this information, an application can use these events to trim any unwanted silence in the recorded files by keeping track of the timeline of the events.

New API:

public event EventHandler<VoiceActivityChangedEventArgs> VoiceActivityChanged;
public class VoiceActivityChangedEventArgs : EventArgs {
    public bool IsVoice {get;}
    public TimeSpan TimeStamp {get;}
}

A new encoding file format is supported, that provides more options to the application for Recorder file output. In addition to the already supported format of Windows Media Audio (WMA) at 16Kps, the following formats are also supported.

WMA48 – WMA at 48 Kbps
PCM8K - PCM at 8 KHz, 16 bits per sample
PCM16K – PCM at 16 KHz, 16 bits per sample

New API:

public WmaEncodingFormat EncodingFormat {get; set;}
public enum WmaEncodingFormat {
    Wma16Kbps,
    Wma48Kbps,
    Pcm8Khz,
    Pcm16Khz
}

Introduction of a downloadable run time for applications dependent only on UCMA 2.0 Core SDK (and not on UCMA 2.0 Windows Workflow Activities or UCMA 2.0 Speech SDK)

The downloadable run time is available at http://go.microsoft.com/fwlink/?LinkID=163815.

The updated pre-detection code for this patch containing the aforementioned APIs is as follows.

<Fragment>
  <Property Id="PROPERTY_UCMA_RUNTIME_INSTALLED" Secure="yes" />

    <!-- Gather information on the installed version of UCMA Runtime 3.5 -->
    <Upgrade Id="{7CA5F91F-26AA-42f9-AB67-B85371B1D5E0}">
      <UpgradeVersion Minimum="3.5.6907.0" OnlyDetect="yes" Property="PROPERTY_UCMA_RUNTIME_INSTALLED" />
    </Upgrade>
    <Property Id="PROPERTY_UCMA_RUNTIME_REQUIRED_KB_INSTALLED" Secure="yes" >
        <RegistrySearch Id="RegistrySearch_UCMA_Runtime_KB_Installed" Root="HKLM" Key="Software\Microsoft\Real-Time Communications\{902F4F35-D5DC-4363-8671-D5EF0D26C21D}\982170" Type="raw" />
    </Property>

    <!-- Verify that the correct version of UCMA Runtime 3.5 is installed and block installation if it is not -->
    <Condition Message="[ProductName] installation requires that Microsoft Unified Communications Managed API 2.0 Core Runtime 64-bit version 3.5.6907 and KB982170 are already installed. Installation cannot continue.">
        <![CDATA[PATCH Or MSIPATCHREMOVE Or REMOVE Or (PROPERTY_UCMA_RUNTIME_INSTALLED And PROPERTY_UCMA_RUNTIME_REQUIRED_KB_INSTALLED)]]>
    </Condition>
</Fragment>

About This Release

Support for the deployment of 64-bit UCMA applications

Introduction of the default routing ApplicationEndpoint

Introduction of support for SIP DNS load balancing

Introduction of a platform interoperability mode with SIP PSTN gateways and IP-PBXs for telephony scenarios

Support for diversion

Enhanced call setup failure diagnostics and Quality of Experience

Support for sampling rate for both stream directions

Support for in-band fax tone detection (CNG 1100Hz)

Support for Player playback speed

Improved Recorder

Introduction of a downloadable run time for applications dependent only on UCMA 2.0 Core SDK (and not on UCMA 2.0 Windows Workflow Activities or UCMA 2.0 Speech SDK)

Additional resources