RemotePresenceView

The RemotePresence class is obsolete in Microsoft Unified Communications Managed API (UCMA) 3.0, and is replaced by a class that is more flexible and usable—the RemotePresenceView class.

RemotePresenceView Capabilities

A presence view is a unified way to request presence information for a set of presentities. An application can create one or more RemotePresenceView instances, each with its own set of remote presentities. Each RemotePresenceView instance can be configured by passing a RemotePresenceViewSettings instance to the RemotePresenceView constructor. The SubscriptionMode property on a RemotePresenceViewSettings instance determines how the presence information is obtained for presentities, specifically the subscription mode and polling interval. The PollingInterval property on the RemotePresenceViewSettings instance specifies how often polling should take place.

The SubscriptionMode property on a RemotePresenceViewSettings instance can have one of the following values.

Value	Description
Default	The most commonly used mode, where persistent subscription is attempted. If the subscription attempt fails, the view automatically switches to polling mode under certain error conditions (such as when the subscription limit is reached for the presentity).
Persistent	All presence changes receive immediate notifications.
Polling	A presentity's presence is polled for at specific time intervals. The interval is specified by the PollingInterval property. Polling to Public Internet Cloud (PIC) or Federated presentities does not result in presence notifications, as they do not support that subscription mode. For such presentities, use a persistent subscription.

Presentities can be dynamically added to or removed from the view any time during the operation of the view, by the use of the StartSubscribingToPresentities(IEnumerable<RemotePresentitySubscriptionTarget>) and StartUnsubscribingToPresentities(IEnumerable<String>) methods. At any time, an application can obtain a snapshot of all presentities in a view, using the GetPresentities() method.

The state of a subscription to each presentity can be tracked by registering to receive notifications when the SubscriptionStateChanged event is raised.

If a subscription succeeds, the state of the presence subscription becomes Subscribed or Polling (values of the RemotePresentitySubscriptionState enumerated type). The actual presence notifications can be received by registering to receive notifications when the PresenceNotificationReceived event is raised.

If an exception is thrown in an attempt to subscribe to a presentity, the state of the subscription becomes Terminated (a value of the RemotePresentitySubscriptionState enumerated type)and the remote presentity is automatically removed from the view.

When a view is no longer needed, it can be unattached from the endpoint by calling the BeginTerminate(AsyncCallback, Object) and EndTerminate(IAsyncResult) methods.

There is no limit to the number of presentities in a view or the number of views that can be created from an endpoint. All views that have not been terminated on an endpoint can be obtained by calling the GetRemotePresenceViews() method. This method can be accessed through the on the PresenceServices property on the endpoint.

RemotePresenceView is designed to be more scalable and to optimize network traffic by batching several polling requests and caching the presence of remote presentities locally. Persistent subscriptions to bots and automated services are switched to polling mode automatically as their presence information rarely changes.

The number of presence categories being subscribed to for the Default or Persistent subscription mode can be modified before the endpoint is created (by modifying the RemotePresenceSubscriptionCategories property on either the UserPresenceSettings or ApplicationEndpointPresenceSettings objects), but cannot be changed after the endpoint has been created. By default, the contact card, state, services, note, and calendar data presence categories are subscribed to.

In contrast, a view created for polling can configure the list of categories at any time during its lifetime by a call to the SetPresenceSubscriptionCategoriesForPolling(IEnumerable<String>) method.

All views belonging to an endpoint can be refreshed at a single time by calls to the BeginRefreshRemotePresenceViews(AsyncCallback, Object) and EndRefreshRemotePresenceViews(IAsyncResult) methods on the endpoint’s PresenceServices property. Refreshing all views is resource-intensive, so applications are advised to limit its usage.

Subscriptions to targets connected to a given server can be batched.

Context Data

To subscribe to remote presentities in a presence view, a RemotePresentitySubscriptionTarget instance must be created for each target. This RemotePresentitySubscriptionTarget instance indicates the SIP URI of that target and an optional context data property, ContextData, that indicates whether the presentity is to be informed about this subscription. When the ContextData property is non-null, the remote presentity is notified of the subscription. This notification is intended to prompt the remote presentity to assign an appropriate container membership, such as Workgroup or Friends and Family. For more information, see LocalOwnerPresence.

In other situations, such as in an ad hoc conversation window or looking at presence in an e-mail, the RemotePresenceView can be used to obtain presence information based on the current default permissions. In this case the SubscriptionContext property should not be set; otherwise unnecessary prompts are sent to the subscription targets.

Presence Query

If a one-time presence query to a remote presentity is desired, creating a view and tearing it down is a suboptimal solution for an application. In addition, the application needs to wait and track whether all presence information has been received.

An alternative is to use the BeginPresenceQuery(IEnumerable<String>, [], EventHandler<RemotePresentitiesNotificationEventArgs>, AsyncCallback, Object) and EndPresenceQuery(IAsyncResult) methods on the endpoint’s PresenceServices property.

RemotePresenceView State Transitions

The RemotePresenceView state transitions for the subscription state of a target are shown in the following illustration. The state values are the members of the RemotePresentitySubscriptionState enumerated type.

1. The transition from Idle to Subscribing occurs when the application calls StartSubscribingToPresentities(IEnumerable<RemotePresentitySubscriptionTarget>) with the SubscriptionMode property on a RemotePresenceViewSettings instance set to Default or Persistent.

2. The transition from Subscribing to Subscribed occurs when the subscription to the remote presentity succeeds.

3. The transition from Subscribing to Terminating occurs when the subscription to the remote presentity fails.

4. The transition from Subscribing to WaitingForRetry occurs for either of the following reasons:

   • For a Communicator 2005 presentity, the server requests UCMA 3.0 to try subscribing again at a later time. At the end of this period the Communicator 2005 presentity is converted to an enhanced presence user.

   • For a remote presentity that belongs to a cross pool, the server requests UCMA 3.0 to try subscribing to the cross-pool server.

5. The transition from WaitingForRetry to Subscribing occurs within 10 seconds, when the attempt to subscribe is made again for the reasons given in step 4.

6. The transition from Subscribed to WaitingForRetry occurs for a number of reasons, such as connection failures (for response codes such as 481 Call Leg Unavailable, 480 Temporarily Unavailable, or 504 Server Timeout) or when the server requests UCMA 3.0 to close this subscription and create a new subscription. This action can happen at any time.

7. The transition from Subscribed to Terminating occurs when the application calls StartUnsubscribingToPresentities(IEnumerable<String>) or BeginTerminate(AsyncCallback, Object).

8. The transition from Terminating to Terminated occurs when the subscription ends, whether or not it is successful.

9. The transition from WaitingForRetry to Terminating occurs when the application is unsubscribing to the target, and the state is WaitingForRetry.

10. The transition from Idle to Polling occurs when the application calls StartSubscribingToPresentities and the value of the SubscriptionMode property is Polling.

11. The transition from Subscribing to Polling can occur when the presentity being subscribed to is an automated service.

12. The transition from Polling to Terminating can occur when StartUnsubscribingToPresentities or BeginTerminate is called on the view.