This feature allows a client session to receive notifications about changes to selected topics. More...

Inheritance diagram for PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicNotifications:

Public Member Functions
Task< INotificationRegistration >	AddListenerAsync (ITopicNotificationListener listener)
	Registers a listener to receive topic notifications. More...

Task< INotificationRegistration >	AddListenerAsync (ITopicNotificationListener listener, CancellationToken cancellationToken)
	Registers a listener to receive topic notifications. More...

Additional Inherited Members
Properties inherited from PushTechnology.ClientInterface.Client.Features.IFeature
ISession	Session `[get]`
	Returns the session that the feature is associated with. More...

Detailed Description

This feature allows a client session to receive notifications about changes to selected topics.

Notifications

Sessions receive notifications via ITopicNotificationListener. The listener will be provided with the ITopicSpecification for all topics bound to paths that match registered selectors, and any subsequent notifications for the selected topics on those paths, via ITopicNotificationListener.OnTopicNotification(string, ITopicSpecification, NotificationType). Notifications will only be emitted for paths where a topic is bound.

For example, with a registered selector "?a//", if a topic is added at path a/b/c/d with no topics bound to paths higher in the hierarchy ITopicNotificationListener.OnTopicNotification(string, ITopicSpecification, NotificationType) will be called once with a topic path of "a/b/c/d", a notification type of NotificationType.ADDED, and the topic's associated ITopicSpecification.

The nature of the notification is provided by the NotificationType enum. NotificationType.ADDED and NotificationType.REMOVED represent structural changes to the topic tree. NotificationType.SELECTED indicates that a pre-existing topic has been selected by a new registered selector, and similarly NotificationType.DESELECTED indicates that a topic is no longer selected because of changes to the set of registered selectors for the listener.

Selection and deselection

Registered ITopicNotificationListener will receive notifications for all topics matching registered selections. Selection of topics using ITopicSelector expressions is provided via the INotificationRegistration associated for a specific listener.

A session can request selections at any time, even if the topics do not exist at the server. Selections are stored on the server and any subsequently added topics that match registered selectors will generate notifications.

Immediate descendant notifications

Listeners will be informed about the presence or absence of unselected immediate descendants via ITopicNotificationListener.OnDescendantNotification(string, NotificationType). This allows listeners to determine whether to select deeper topic paths in order to walk the topic tree.An immediate descendant is defined as the first bound topic on any branch below a given topic path.

For example, for topics at "a/b", "a/c", "a/c/d", "a/e/f/g", the immediate descendants of "a" would be "a/b", "a/c", "a/e/f/g".

Immediate descendant notifications provide a NotificationType to indicate the reason for the notification in the same manner as ITopicNotificationListener.OnTopicNotification(string, ITopicSpecification, NotificationType).

For example, with a registered selector ">a", if a topic is added at path a/b then ITopicNotificationListener.OnDescendantNotification(string, NotificationType) will be called with a topic path of "a/b" and a notification type of NotificationType.ADDED. If a topic was subsequently added at path a/b/c, no further notifications will be received until INotificationRegistration.SelectAsync(string) was used to select the deeper topic path ">a/b".

Access control

A listener will only be notified about topics for which the session has Types.TopicPermission.SELECT_TOPIC and Types.TopicPermission.READ_TOPIC permissions. Types.TopicPermission.SELECT_TOPIC determines which selectors a listener may register. Types.TopicPermission.READ_TOPIC determines which selected topics the client may receive notifications for.

Added in version 6.1.

Member Function Documentation

Task<INotificationRegistration> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicNotifications.AddListenerAsync ( ITopicNotificationListener listener )

Registers a listener to receive topic notifications.

If the operation completes successfully, the returned Task result will be a INotificationRegistration, which may be used to later close the listener and remove it from the server.

This method is the same as calling AddListenerAsync(ITopicNotificationListener, CancellationToken) with CancellationToken.None.

Parameters

listener The listener to receive topic specification notifications.

Returns: The Task representing the current operation.

Exceptions

Session.SessionClosedException The calling session is closed. Thrown by the returned Task.

See Also: AddListenerAsync(ITopicNotificationListener, CancellationToken)

Task<INotificationRegistration> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicNotifications.AddListenerAsync	(	ITopicNotificationListener	listener,
		CancellationToken	cancellationToken
	)