API Changes in UCMA 3.0 for High Availability and Failover
This topic discusses the changes in Microsoft Unified Communications Managed API (UCMA) 3.0 associated with High Availability and Failover.
SipEndpoint Class
The following API changes appear as public changes in the SipEndpoint class. When a SIP NOTIFY message is received with USC unavailable the RegistrationStateChanged event is raised. In the associated RegistrationStateChangedEventArgs object, the Reason property is set to None (a value of the RegistrationTransitionReason enumeration) and the UserServicesState property is set to Unavailable (a value of the ServiceState enumeration).
When the registration is subsequently healed by means of a registration refresh, the RegistrationStateChanged event is raised, and the Reason property is set to Refreshed, and UserServicesState property is set to Available. The SipEndpoint class does not expose UserServicesState as a property.
ServiceState Enumeration
The ServiceState enumeration is new in the Microsoft Unified Communications Managed API (UCMA) 3.0. The values in this enumeration represent the state of a service.
The enumeration values and their descriptions are shown in the following table.
Value |
Description |
|---|---|
Unknown |
The state of the service is unknown. |
Available |
The service is available. |
Unavailable |
The service is unavailable. |
RegistrationStateChangedEventArgs Class
Three new properties have been added to the RegistrationStateChangedEventArgs class. These properties and their descriptions are shown in the following table.
Property |
Description |
|---|---|
Gets the reason, if known, for the state transition. |
|
Gets the message data containing the message received when a state transition occurs. The value of this property is null when the state transition contains no message data. |
|
Gets the availability state of the User Services pool. |
LocalEndpointStateChangedEventArgs Class
The new properties on the LocalEndpointStateChangedEventArgs class are shown in the following table. Most of the Reason values are self-explanatory, but when a SIP NOTIFY message is received, the Reason value is RegistrarNotificationReceived and the Notification value indicates the type of notification.
Property |
Description |
|---|---|
Gets the message received when a state transition occurs. Can be null if the state transition does not contain any message data. |
|
Gets the reason for the state change, a value in the LocalEndpointStateTransitionReason enumeration. |
MessageData Property
The MessageData property on the LocalEndpointStateChangedEventArgs class is of type SipMessageData.
Reason Property
The Reason property on the LocalEndpointStateChangedEventArgs class can be set to a value in the LocalEndpointStateTransitionReason enumeration. These values are shown in the following table.
Value |
Description |
|---|---|
None |
No SIP NOTIFY message or a SIP NOTIFY message of unknown type. |
OwnerDisabledOrRemoved |
The user or application endpoint owner has been disabled or removed. |
RegistrationRefreshFailed |
Registration refresh attempt failed. |
RegistrationRefreshSucceeded |
Registration was refreshed successfully. |
TooManyActiveEndpoints |
The number of active endpoints exceeds the limit. |
SipSubscription Class
There are no public API changes in the SipSubscription class, but there are behavior changes that are triggered only from the UCMA platform. When used as part of the UCMA platform, the retry behavior of SipSubscription objects is optimized to eliminate unnecessary attempts to recover when the User Services pool is unresponsive. When the User Services pool does not respond, a failure to refresh a subscription does not cause a SipSubscription instance to terminate. The UCMA platform triggers this behavior only for subscriptions tied to the User Services pool that the owner is homed on.
LocalOwnerPresence and ContactGroupServices Classes
There are no new API. When the User Services pool is offline, LocalOwnerPresence and ContactGroupServices objects change state to WaitingForRetry (see SubscriptionSignalingState) with a TransitionReason value of ServerEvent. In this state, publish operations fail with InvalidOperationException being thrown. Also, if the CurrentState property of the underlying SipSubscription instance changes to Terminated, the CurrentState property on the LocalOwnerPresence instance changes to WaitingForRetry instead of Idle. When the User Services pool finally recovers, the subscription will be re-established.
RemotePresence Class
The home pool subscription of RemotePresence objects is the same as that of LocalOwnerPresence objects.