Call Admission Control API Changes

The call admission control capability added in Microsoft Unified Communications Managed API (UCMA) 3.0 adds one class and makes several additions to existing classes and enumerated types. These changes are summarized in this topic.

New API

The FailureRequestException class has been added.

FailureRequestException Class

The FailureRequestException defines the exception to be thrown when a failure message is received as a SIP request message. The public members on the FailureRequestException class, excluding the overridden methods from the base class, are shown in the following table.

Class member	Description
FailureRequestException() constructor	Creates a new instance of the FailureRequestException class.
FailureRequestException(String) constructor	Creates a new instance of the FailureRequestException class.
FailureRequestException(SerializationInfo, StreamingContext) constructor	Creates a new instance of the FailureRequestException class.
GetObjectData(SerializationInfo, StreamingContext) method	Populates SerializationInfo with the data needed to serialize the object.
ToString() method	Returns the string representation of the diagnostic header.
DiagnosticInformation property	Gets the DiagnosticHeader representing the diagnostic information received as an ms-diagnostics or ms-diagnostics-public header in the request. If the message contains both headers, then this is considered to represent ms-diagnostics header information.
RequestData property	Gets the request data. Can be null if the exception is thrown in the case where no request data was received.
WarningInformation property	Gets a list of warning headers representing warning information received with Warning Header in the request.

Revised APIs

Several changes have been made to existing classes and enumerated types. For each class or enumerated type that has changed, the new members are listed.

OfferAnswerFailureReason Enumeration

Two new values have been added to the OfferAnswerFailureReason enumerated type. These values are used to convey the media policy result from the media layer to the signaling layer. The new values are shown in the following table.

Enumeration value	Description
RedirectDueToBandwidthPolicy	Bandwidth policy requested that this call be redirected.
FailDueToBandwidthPolicy	Bandwidth policy did not allow this call to be established.

CallAcceptOptions Class

A new property has been added to the CallAcceptOptions class. The property enables an application to choose whether it follows system bandwidth policy. When bandwidth allocation fails, the media provider throws OfferAnswerException with its FailureReason property set to either RedirectDueToBandwidthPolicy or FailDueToBandwidthPolicy. If the value of the FailureReason property is RedirectDueToBandwidthPolicy, the call will be converted to a PSTN call.

Some applications are able to handle redirection to PSTN. For such applications, the RedirectDueToBandwidthPolicyEnabled property acts as a switch to turn on redirection. When the media provider’s failure reason is RedirectDueToBandwidthPolicy, a value of true for RedirectDueToBandwidthPolicyEnabled allows the application to send a different header so that the call can be redirected to PSTN.

Class member	Description
RedirectDueToBandwidthPolicyEnabled property	Gets or sets whether to redirect the call when recommended by the bandwidth policy. By default, if an incoming call fails bandwidth allocation, it will be declined. An application can redirect this call by way of PSTN by setting this property to true before it accepts the call.

CallStateTransitionReason Enumeration

A new value has been added to the CallStateTransitionReason enumeration. When a call is redirected, the server sends a SIP 199 status code to the caller to denote that the call might be delayed.

Enumeration value	Description
CallDelayed	The call establishment operation might be delayed due to redirection.

SdpAnswerStatus Enumeration

A new value has been added to the SdpAnswerStatus enumerated type. When SDP negotiation fails due to a Call Admission Control check, the caller receives a 488 error code with diagnostic headers. The signaling layer calls SetAnswer with a null answer and the following answer status to inform the media layer that SDP negotiation failed.

Enumeration value	Description
NotAcceptableDueToBandwidthPolicy	The call establishment operation might be delayed due to redirection.

FailureResponseException Class

A new property has been added to the FailureResponseException class.

Enumeration value	Description
WarningInformation	Gets a collection of WarningHeader objects. Applications can query this collection to get bandwidth-related warning headers.