Interface ITopics

This feature allows a client session to subscribe to topics to receive streamed topic updates, fetch the state of topics and/or update topics with new values.

Inherited Members

ITopicViews.CreateTopicViewAsync(String, String)

ITopicViews.CreateTopicViewAsync(String, String, CancellationToken)

ITopicViews.ListTopicViewsAsync()

ITopicViews.ListTopicViewsAsync(CancellationToken)

ITopicViews.GetTopicViewAsync(String)

ITopicViews.GetTopicViewAsync(String, CancellationToken)

ITopicViews.RemoveTopicViewAsync(String)

ITopicViews.RemoveTopicViewAsync(String, CancellationToken)

ITopicUpdate.SetAsync<TValue>(String, TValue)

ITopicUpdate.SetAsync<TValue>(String, TValue, CancellationToken)

ITopicUpdate.SetAsync<TValue>(String, TValue, IUpdateConstraint)

ITopicUpdate.SetAsync<TValue>(String, TValue, IUpdateConstraint, CancellationToken)

ITopicUpdate.AddAndSetAsync<TValue>(String, ITopicSpecification, TValue)

ITopicUpdate.AddAndSetAsync<TValue>(String, ITopicSpecification, TValue, CancellationToken)

ITopicUpdate.AddAndSetAsync<TValue>(String, ITopicSpecification, TValue, IUpdateConstraint)

ITopicUpdate.AddAndSetAsync<TValue>(String, ITopicSpecification, TValue, IUpdateConstraint, CancellationToken)

ITopicUpdate.CreateUpdateStream<TValue>(String)

ITopicUpdate.CreateUpdateStream<TValue>(String, IUpdateConstraint)

ITopicUpdate.CreateUpdateStream<TValue>(String, ITopicSpecification)

ITopicUpdate.CreateUpdateStream<TValue>(String, ITopicSpecification, IUpdateConstraint)

ITopicUpdate.NewUpdateStreamBuilder()

ITopicUpdate.ApplyJSONPatchAsync(String, String)

ITopicUpdate.ApplyJSONPatchAsync(String, String, CancellationToken)

ITopicUpdate.ApplyJSONPatchAsync(String, String, IUpdateConstraint)

ITopicUpdate.ApplyJSONPatchAsync(String, String, IUpdateConstraint, CancellationToken)

IFeature.Session

Namespace: PushTechnology.ClientInterface.Client.Features

Assembly: Diffusion.Client.dll

Syntax

public interface ITopics : ITopicViews, ITopicUpdate, IFeature

Remarks

Specifically, the feature provides the ability to:

• Subscribe to topics and specify streams to receive updates.
• Fetch the current state of topics (even if not subscribed).
• By extending the ITopicUpdate feature, update topics with new values.
• By extending the ITopicViews feature, manage topic views.

Subscription and unsubscription

A session can issue requests to subscribe to topics at any time, even if the topics do not exist at the server. Each subscription request provides a ITopicSelector that is evaluated by the server to select matching topics. The session will be subscribed to any topics that match the selector unless they are already subscribed, or the session has insufficient permission. The subscription request is also retained at the server and the session will be automatically subscribed to newly created topics that match the selector (unless a subsequent unsubscription cancels the request).

Sessions receive notifications from topics that they are subscribed to via subscription streams (see below). When a session is subscribed to a topic, all matching streams will first receive a subscription notification that provides details about the topic. If the server has a value for the topic, the value will be delivered to the streams before any other notifications.

A session can unsubscribe from topics at any time. This is also specified using a topic selector. On unsubscription, matching streams are notified via the OnUnsubscription(String, ITopicSpecification, TopicUnsubscribeReason) notification. This notification will give the reason for unsubscription (for example, by request of the session, request of the server, or topic removal).

Subscriptions and unsubscriptions can occur for reasons other than requests from the session. A session can be subscribed to or unsubscribed from a topic by another session using the ISubscriptionControl feature. The removal of a topic also automatically causes unsubscription for subscribed sessions.

Subscription requests are subject to authorization checks. The session must have SELECT_TOPIC permission for the topic selector used to subscribe. Matching topics will be further filtered to those for which the session has READ_TOPIC permission.

Topic selection scopes

Topic selection scopes allow an application with multiple components to use a single Diffusion session. An application component can use a topic selection scope to manage a set of selectors that is unaffected by unsubscriptions performed by other application components. The session will be subscribed to all topics with paths matching a selector in any scope. The unsubscribe operation removes a selector from specific scopes.

A scope may be specified to a SubscribeAsync(String, String)" or UnsubscribeAsync(String, String)" method, indicating that the selection only applies to that scope. The server manages scopes to ensure that unsubscriptions applied to one scope do not affect another.

Scope names are case sensitive. A scope name may not begin with the character $ as this is reserved for internal use.

Unsubscription using a wildcard selector that indicates all topics (such as "?.*//") effectively removes the scope.

An application can request unsubscription from all scopes using UnsubscribeAllScopesAsync(String).

An empty string is used as the default topic selection scope for all methods that do not explicitly specify a scope.

Subscription streams

A session can listen to subscription events and updates for a selection of topics by adding one or more streams. A stream is registered using a topic selector which specifies the topics that the stream applies to. When an update is received for a topic then it will be routed to every stream that matches both the topic selector and the stream's value type. If more than one stream matches, all will receive the update; the order in which they are notified is not defined.

A stream can be added several times for different selectors. If the same stream (determined by object.Equals(object)) is registered for several selectors that match an event, the stream will only be notified of the event once. The mapping of topic selectors to streams is maintained locally in the client process.

It is also possible to add one or more fallback streams which will receive updates that do not match any stream registered with a selector. This is useful for default processing or simply to catch unprocessed updates. A fallback stream can be added using AddFallbackStream<TValue>(IValueStream<TValue>). Zero, one, or more fallback streams may be assigned. If no fallback stream is specified, any updates that are not routed to any other stream will simply be discarded.

If the session is already subscribed to a topic when a matching stream is added, the stream will immediately receive a subscription notification. For most topic types, the latest value is locally cached and will be provided to the stream following the subscription notification.

A stream will receive an OnClose() callback when unregistered and an OnError(ErrorReason)) callback with a SESSION_CLOSED reason, if the session is closed.

Value streams

A IValueStream<TValue> receives values for matching topics as and when updates are received from the server. Delta updates received from the server are automatically applied to locally cached values so that the stream always receives full values for each update.

Value streams are typed to a specified value class and only updates for compatible topics will be routed to the stream. The following table shows how the value class maps to compatible topic types that will be routed to the stream:

Value Class	Compatible Topic Types
IJSON	JSON, STRING, INT64, DOUBLE
string	STRING
long	INT64
double	DOUBLE
IBinary	BINARY
IBytes	JSON, STRING, INT64, DOUBLE, BINARY, RECORD_V2
IRecordV2	RECORD_V2

Value stream implementations can be added using AddStream<TValue>(String, IValueStream<TValue>).

A value stream can be added to received updates from ITimeSeries topics using AddTimeSeriesStream<TValue>(String, IValueStream<IEvent<TValue>>). The following table shows how the value class specified when adding the stream maps to the event value class of time series topics that will be routed to the stream:

Value Class	Compatible Topic Types
IJSON	JSON, STRING, INT64, DOUBLE
string	STRING
long	INT64
double	DOUBLE
IBinary	BINARY
IBytes	JSON, STRING, INT64, DOUBLE, BINARY, RECORD_V2
IRecordV2	RECORD_V2

Fetch

A session can issue a request to fetch details of a topic or topics (subject to authorization) at any time. The topics required are specified using a topic selector.

The results of a fetch will return the topic path and type of each selected topic. The results may also optionally return the topic values and/or properties.

A new request can be created using FetchRequest and modified to specify additional requirements of the fetch operation. The request is issued to the server using the FetchAsync(String) method on the request. This will return the results via a Task.

Access control

A session must have SELECT_TOPIC permission for the topic selector used to subscribe to fetch. The topics that result from a subscription or fetch request are further filtered using the READ_TOPIC permission.

The READ_TOPIC permission is required to retrieve the topic details.

No access control restrictions are applied to unsubscription.

Accessing the feature

This feature may be obtained from an ISession as follows:

var topicControl = session.Topics;

Added in version 5.0.

Properties

FetchRequest

Gets an unconfigured fetch request.

Declaration

IFetchRequest FetchRequest { get; }

Property Value

Type	Description
IFetchRequest	The unconfigured fetch request.

Remarks

If the request is invoked by calling FetchAsync(String), the fetch result will provide the paths and types of all of the topics which the session has permission to read.

You will usually want to restrict the query to a subset of the topic tree, and to retrieve the topic values and/or properties. This is achieved by applying one or more of the fluent builder methods to produce more refined requests.

For example:

var result = await topics.FetchRequest.WithValues<string?>.FetchAsync( "A/B//" );

See Also

IFetchRequest

IFetchRequest<TValue>

Methods

AddFallbackStream<TValue>(IValueStream<TValue>)

Adds a fallback value stream.

Declaration

void AddFallbackStream<TValue>(IValueStream<TValue> stream)

Parameters

Type	Name	Description
IValueStream<TValue>	stream	The stream to add.

Type Parameters

Name	Description
TValue	The value type.

Remarks

See ITopics documentation for full details regarding the use of fallback streams.

Exceptions

Type	Condition
System.ArgumentNullException	The stream is null.

AddStream<TValue>(ITopicSelector, IValueStream<TValue>)

Adds a value stream to receive topic events for topics that match a given ITopicSelector and have a value type that matches the specified type.

Declaration

[Obsolete("Topic selectors are now deprecated and will be removed in a future release. Instead, use the AddStream method that accepts a string argument.", false)]
void AddStream<TValue>(ITopicSelector selector, IValueStream<TValue> stream)

Parameters

Type	Name	Description
ITopicSelector	selector	The selector of one or more topics.
IValueStream<TValue>	stream	The stream to add.

Type Parameters

Name	Description
TValue	The value type.

Remarks

See ITopics documentation for full details of the use of value streams.

Caution

Deprecated since 6.4. Topic selectors are no longer verified locally by the client library. Instead System.String expressions will be sent to (and verified by) the Diffusion server. This method will be removed in a future release.

Exceptions

Type	Condition
System.ArgumentNullException	The selector or stream is null.

AddStream<TValue>(String, IValueStream<TValue>)

Adds a value stream to receive topic events for topics that match a given ITopicSelector expression and have a value type that matches the specified type.

Declaration

void AddStream<TValue>(string topics, IValueStream<TValue> stream)

Parameters

Type	Name	Description
System.String	topics	The topics as a ITopicSelector expression.
IValueStream<TValue>	stream	The stream to add.

Type Parameters

Name	Description
TValue	The value type.

Remarks

See ITopics documentation for full details of the use of value streams.

Exceptions

Type	Condition
System.ArgumentNullException	The topics expression or stream is null.
System.ArgumentException	The topics expression is not a valid selector expression.

AddTimeSeriesStream<TValue>(ITopicSelector, IValueStream<IEvent<TValue>>)

Adds a value stream to receive topic events for time series topics that match a given ITopicSelector and have a compatible time series value type.

Declaration

[Obsolete("Topic selectors are now deprecated and will be removed in a future release. Instead, use the AddTimeSeriesStream method that accepts a string argument.", false)]
void AddTimeSeriesStream<TValue>(ITopicSelector selector, IValueStream<IEvent<TValue>> stream)

Parameters

Type	Name	Description
ITopicSelector	selector	The ITopicSelector.
IValueStream<IEvent<TValue>>	stream	The time series value stream.

Type Parameters

Name	Description
TValue	The time series value type.

Remarks

See the ITopics documentation for details of the use of value streams, and the ITimeSeries documentation for details of time series topics.

This method must be used instead of AddStream<TValue>(ITopicSelector, IValueStream<TValue>) to add a IValueStream<TimeSeries.IEvent<TValue>>. The stream can be removed with RemoveStream(IStream).

Caution

Deprecated since 6.4. Topic selectors are no longer verified locally by the client library. Instead System.String expressions will be sent to (and verified by) the Diffusion server. This method will be removed in a future release.

Exceptions

Type	Condition
System.ArgumentNullException	The selector or stream is null.

AddTimeSeriesStream<TValue>(String, IValueStream<IEvent<TValue>>)

Adds a value stream to receive topic events for time series topics that match a given ITopicSelector expression and have a compatible time series value type.

Declaration

void AddTimeSeriesStream<TValue>(string topics, IValueStream<IEvent<TValue>> stream)

Parameters

Type	Name	Description
System.String	topics	The ITopicSelector expression.
IValueStream<IEvent<TValue>>	stream	The time series value stream.

Type Parameters

Name	Description
TValue	The time series value type.

Remarks

See the ITopics documentation for details of the use of value streams, and the ITimeSeries documentation for details of time series topics.

This method must be used instead of AddStream<TValue>(String, IValueStream<TValue>) to add a IValueStream<TimeSeries.IEvent<TValue>>. The stream can be removed with RemoveStream(IStream).

Exceptions

Type	Condition
System.ArgumentNullException	The topics expression or stream is null.
System.ArgumentException	The topics expression is not a valid selector expression.

RemoveStream(IStream)

Removes a stream.

Declaration

void RemoveStream(IStream stream)

Parameters

Type	Name	Description
IStream	stream	The value stream to remove.

Remarks

More formally, this method removes all streams that compare equal to the given stream, regardless of the topic selector for which they are registered. It will also remove any fallback stream equal to the given stream. If there are no such streams, no changes are made.

Exceptions

Type	Condition
System.ArgumentNullException	The stream is null.

SubscribeAsync(ITopicSelector)

Requests subscription to topics.

Declaration

[Obsolete("Topic selectors are now deprecated and will be removed in a future release. Instead, use the SubscribeAsync method that accepts a string argument.", false)]
Task<object> SubscribeAsync(ITopicSelector selector)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to subscribe to.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This is equivalent to calling SubscribeAsync(ITopicSelector, String) using the default selection scope. See Topic Selection Scopes.

If the task completes successfully, the Task result will be null.

Caution

Deprecated since 6.4. Topic selectors are no longer verified locally by the client library. Instead System.String expressions will be sent to (and verified by) the Diffusion server. This method will be removed in a future release.

Exceptions

Type	Condition
System.ArgumentNullException	The selector is null.
SessionClosedException	The session is closed. Thrown by the returned Task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permissions for the given selector. Thrown by the returned Task.

See Also

SubscribeAsync(ITopicSelector, CancellationToken)

SubscribeAsync(ITopicSelector, String)

Requests subscription to topics.

Declaration

Task<object> SubscribeAsync(ITopicSelector selector, string scope)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to subscribe to.
System.String	scope	Specifies the scope of the selection. See Topic Selection Scopes.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

The session will become subscribed to each existing topic matching the selector unless the session is already subscribed to the topic, or the session does not have READ_TOPIC permission for the topic path. For each topic to which the session becomes subscribed, a subscription notification and initial value (if any) will be delivered to registered value streams before the returned Task completes.

The subscription request is also retained at the server and the session will be automatically subscribed to newly created topics that match the selector (unless a subsequent unsubscription cancels the request).

Exceptions

Type	Condition
System.ArgumentNullException	The selector is null or scope is null.
System.ArgumentException	The scope starts with '$'.
SessionClosedException	The session is closed. Thrown by the returned Task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permissions for the given selector. Thrown by the returned Task.

See Also

SubscribeAsync(ITopicSelector, String, CancellationToken)

SubscribeAsync(ITopicSelector, String, CancellationToken)

Requests subscription to topics.

Declaration

Task<object> SubscribeAsync(ITopicSelector selector, string scope, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to subscribe to.
System.String	scope	Specifies the scope of the selection. See Topic Selection Scopes.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

The session will become subscribed to each existing topic matching the selector unless the session is already subscribed to the topic, or the session does not have READ_TOPIC permission for the topic path. For each topic to which the session becomes subscribed, a subscription notification and initial value (if any) will be delivered to registered value streams before the returned Task completes.

The subscription request is also retained at the server and the session will be automatically subscribed to newly created topics that match the selector (unless a subsequent unsubscription cancels the request).

Exceptions

Type	Condition
System.ArgumentNullException	The selector is null or scope is null.
System.ArgumentException	The scope starts with '$'.
SessionClosedException	The session is closed. Thrown by the returned Task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permissions for the given selector. Thrown by the returned Task.

SubscribeAsync(ITopicSelector, CancellationToken)

Requests subscription to topics.

Declaration

[Obsolete("Topic selectors are now deprecated and will be removed in a future release. Instead, use the SubscribeAsync method that accepts a string argument.", false)]
Task<object> SubscribeAsync(ITopicSelector selector, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to subscribe to.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This is equivalent to calling SubscribeAsync(ITopicSelector, String, CancellationToken) using the default selection scope. See Topic Selection Scopes.

If the task completes successfully, the Task result will be null.

Caution

Deprecated since 6.4. Topic selectors are no longer verified locally by the client library. Instead System.String expressions will be sent to (and verified by) the Diffusion server. This method will be removed in a future release.

Exceptions

Type	Condition
System.ArgumentNullException	The selector is null.
SessionClosedException	The session is closed. Thrown by the returned Task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permissions for the given selector. Thrown by the returned Task.

SubscribeAsync(String)

Requests subscription to topics.

Declaration

Task<object> SubscribeAsync(string topics)

Parameters

Type	Name	Description
System.String	topics	Specifies the topics to request subscription to.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This is equivalent to calling SubscribeAsync(String, String) using the default selection scope. See Topic Selection Scopes.

The given topics expression will be evaluated by the server.

The session will become subscribed to each existing topic matching the selector unless the session is already subscribed to the topic, or the session does not have READ_TOPIC permission for the topic path. For each topic to which the session becomes subscribed, a subscription notification and initial value (if any) will be delivered to registered value streams before the returned task completes.

The subscription request is also retained at the server and the session will be automatically subscribed to newly created topics that match the selector (unless a subsequent unsubscription cancels the request).

If the task completes successfully, the Task result will be null.

Exceptions

Type	Condition
System.ArgumentNullException	The topics expression is null.
TopicSelectorFormatException	The topics expression is not a valid selector expression.
SessionClosedException	The session is closed. Thrown by the returned Task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permissions for the given selector expression. Thrown by the returned Task.

See Also

SubscribeAsync(String, CancellationToken)

SubscribeAsync(String, String)

Requests subscription to topics.

Declaration

Task<object> SubscribeAsync(string topics, string scope)

Parameters

Type	Name	Description
System.String	topics	Specifies the topics to request subscription to.
System.String	scope	Specifies the scope of the selection. See Topic Selection Scopes.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This is equivalent to calling SubscribeAsync(ITopicSelector, String) with a selector parsed using Parse(String).

If the task completes successfully, the Task result will be null.

Exceptions

Type	Condition
System.ArgumentNullException	The topics expression is null or scope is null.
System.ArgumentException	The scope starts with '$'.
TopicSelectorFormatException	The topics expression is not a valid selector expression.
SessionClosedException	The session is closed. Thrown by the returned Task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permissions for the given selector expression. Thrown by the returned Task.

See Also

SubscribeAsync(String, String, CancellationToken)

SubscribeAsync(String, String, CancellationToken)

Requests subscription to topics.

Declaration

Task<object> SubscribeAsync(string topics, string scope, CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.String	topics	Specifies the topics to request subscription to.
System.String	scope	Specifies the scope of the selection. See Topic Selection Scopes.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This is equivalent to calling SubscribeAsync(ITopicSelector, String) with a selector parsed using Parse(String).

If the task completes successfully, the Task result will be null.

Exceptions

Type	Condition
System.ArgumentNullException	The topics expression is null or scope is null.
System.ArgumentException	The scope starts with '$'.
TopicSelectorFormatException	The topics expression is not a valid selector expression.
SessionClosedException	The session is closed. Thrown by the returned Task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permissions for the given selector expression. Thrown by the returned Task.

SubscribeAsync(String, CancellationToken)

Requests subscription to topics.

Declaration

Task<object> SubscribeAsync(string topics, CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.String	topics	Specifies the topics to request subscription to.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This is equivalent to calling SubscribeAsync(String, String, CancellationToken) using the default selection scope. See Topic Selection Scopes.

The given topics expression will be evaluated by the server.

If the task completes successfully, the Task result will be null.

Exceptions

Type	Condition
System.ArgumentNullException	The topics expression is null.
TopicSelectorFormatException	The topics expression is not a valid selector expression.
SessionClosedException	The session is closed. Thrown by the returned Task.
SessionSecurityException	The calling session does not have SELECT_TOPIC permissions for the given selector expression. Thrown by the returned Task.

UnsubscribeAllScopesAsync(ITopicSelector)

Unsubscribe topics from all topic selection scopes.

Declaration

Task<object> UnsubscribeAllScopesAsync(ITopicSelector topics)

Parameters

Type	Name	Description
ITopicSelector	topics	The topics to unsubscribe from.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This can be used at any time whilst connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests and will apply to all scopes in use.

Exceptions

Type	Condition
System.ArgumentNullException	The topics expression is null.
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

UnsubscribeAllScopesAsync(ITopicSelector, CancellationToken)

UnsubscribeAllScopesAsync(ITopicSelector, CancellationToken)

Unsubscribe topics from all topic selection scopes.

Declaration

Task<object> UnsubscribeAllScopesAsync(ITopicSelector topics, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ITopicSelector	topics	The topics to unsubscribe from.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This can be used at any time whilst connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests and will apply to all scopes in use.

Exceptions

Type	Condition
System.ArgumentNullException	The topics expression is null.
SessionClosedException	The session is closed. Thrown by the returned Task.

UnsubscribeAllScopesAsync(String)

Unsubscribe topics from all topic selection scopes.

Declaration

Task<object> UnsubscribeAllScopesAsync(string topics)

Parameters

Type	Name	Description
System.String	topics	The topics to unsubscribe from.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This is equivalent to calling UnsubscribeAllScopesAsync(ITopicSelector) with a selector parsed using Parse(String).

Exceptions

Type	Condition
System.ArgumentNullException	The topics expression is null.
TopicSelectorFormatException	The topics expression is not a valid selector expression.
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

UnsubscribeAllScopesAsync(String, CancellationToken)

UnsubscribeAllScopesAsync(String, CancellationToken)

Unsubscribe topics from all topic selection scopes.

Declaration

Task<object> UnsubscribeAllScopesAsync(string topics, CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.String	topics	The topics to unsubscribe from.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This is equivalent to calling UnsubscribeAllScopesAsync(ITopicSelector) with a selector parsed using Parse(String).

Exceptions

Type	Condition
System.ArgumentNullException	The topics expression is null.
TopicSelectorFormatException	The topics expression is not a valid selector expression.
SessionClosedException	The session is closed. Thrown by the returned Task.

UnsubscribeAsync(ITopicSelector)

Unsubscribes from topics.

Declaration

[Obsolete("Topic selectors are now deprecated and will be removed in a future release. Instead, use the UnsubscribeAsync method that accepts a string argument.", false)]
Task<object> UnsubscribeAsync(ITopicSelector selector)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to unsubscribe from.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This is equivalent to calling UnsubscribeAsync(ITopicSelector, String) using the default selection scope. See Topic Selection Scopes.

This can be used at any time while connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

If the task completes successfully, the Task result will be null.

Caution

Deprecated since 6.4. Topic selectors are no longer verified locally by the client library. Instead System.String expressions will be sent to (and verified by) the Diffusion server. This method will be removed in a future release.

Exceptions

Type	Condition
System.ArgumentNullException	The selector is null.
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

UnsubscribeAsync(ITopicSelector, CancellationToken)

UnsubscribeAsync(ITopicSelector, String)

Unsubscribes from topics.

Declaration

Task<object> UnsubscribeAsync(ITopicSelector selector, string scope)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to unsubscribe from.
System.String	scope	Specifies the scope of the selection. See Topic Selection Scopes.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This can be used at any time whilst connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

If the task completes successfully, the Task result will be null.

Exceptions

Type	Condition
System.ArgumentNullException	The selector is null or scope is null.
System.ArgumentException	The scope starts with '$'.
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

UnsubscribeAsync(ITopicSelector, String, CancellationToken)

UnsubscribeAsync(ITopicSelector, String, CancellationToken)

Unsubscribes from topics.

Declaration

Task<object> UnsubscribeAsync(ITopicSelector selector, string scope, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to unsubscribe from.
System.String	scope	Specifies the scope of the selection. See Topic Selection Scopes.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This can be used at any time whilst connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

If the task completes successfully, the Task result will be null.

Exceptions

Type	Condition
System.ArgumentNullException	The selector is null or scope is null.
System.ArgumentException	The scope starts with '$'.
SessionClosedException	The session is closed. Thrown by the returned Task.

UnsubscribeAsync(ITopicSelector, CancellationToken)

Unsubscribes from topics.

Declaration

[Obsolete("Topic selectors are now deprecated and will be removed in a future release. Instead, use the UnsubscribeAsync method that accepts a string argument.", false)]
Task<object> UnsubscribeAsync(ITopicSelector selector, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ITopicSelector	selector	The topics to unsubscribe from.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This is equivalent to calling UnsubscribeAsync(ITopicSelector, String, CancellationToken) using the default selection scope. See Topic Selection Scopes.

This can be used at any time while connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

If the task completes successfully, the Task result will be null.

Caution

Deprecated since 6.4. Topic selectors are no longer verified locally by the client library. Instead System.String expressions will be sent to (and verified by) the Diffusion server. This method will be removed in a future release.

Exceptions

Type	Condition
System.ArgumentNullException	The selector is null.
SessionClosedException	The session is closed. Thrown by the returned Task.

UnsubscribeAsync(String)

Unsubscribes from topics.

Declaration

Task<object> UnsubscribeAsync(string topics)

Parameters

Type	Name	Description
System.String	topics	The topics to unsubscribe from.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This is equivalent to calling UnsubscribeAsync(String, String) using the default selection scope. See Topic Selection Scopes.

This can be used at any time while connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

The given topics expression will be evaluated by the server.

If the task completes successfully, the Task result will be null.

Exceptions

Type	Condition
System.ArgumentNullException	The topics expression is null.
TopicSelectorFormatException	The topics expression is not a valid selector expression.
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

UnsubscribeAsync(String, CancellationToken)

UnsubscribeAsync(String, String)

Unsubscribes from topics.

Declaration

Task<object> UnsubscribeAsync(string topics, string scope)

Parameters

Type	Name	Description
System.String	topics	The topics to unsubscribe from.
System.String	scope	Specifies the scope of the selection. See Topic Selection Scopes.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This is equivalent to calling UnsubscribeAsync(ITopicSelector, String) with a selector parsed using Parse(String).

Exceptions

Type	Condition
System.ArgumentNullException	The topics expression is null or scope is null.
System.ArgumentException	The scope starts with '$'.
TopicSelectorFormatException	The topics expression is not a valid selector expression.
SessionClosedException	The session is closed. Thrown by the returned Task.

See Also

UnsubscribeAsync(String, String, CancellationToken)

UnsubscribeAsync(String, String, CancellationToken)

Unsubscribes from topics.

Declaration

Task<object> UnsubscribeAsync(string topics, string scope, CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.String	topics	The topics to unsubscribe from.
System.String	scope	Specifies the scope of the selection. See Topic Selection Scopes.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This is equivalent to calling UnsubscribeAsync(ITopicSelector, String) with a selector parsed using Parse(String).

Exceptions

Type	Condition
System.ArgumentNullException	The topics expression is null or scope is null.
System.ArgumentException	The scope starts with '$'.
TopicSelectorFormatException	The topics expression is not a valid selector expression.
SessionClosedException	The session is closed. Thrown by the returned Task.

UnsubscribeAsync(String, CancellationToken)

Unsubscribes from topics.

Declaration

Task<object> UnsubscribeAsync(string topics, CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.String	topics	The topics to unsubscribe from.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This is equivalent to calling UnsubscribeAsync(String, String, CancellationToken) using the default selection scope. See Topic Selection Scopes.

This can be used at any time while connected to reduce the set of topics to which the session is subscribed or negate earlier subscription requests.

The given topics expression will be evaluated by the server.

If the task completes successfully, the Task result will be null.

Exceptions

Type	Condition
System.ArgumentNullException	The topics expression is null.
TopicSelectorFormatException	The topics expression is not a valid selector expression.
SessionClosedException	The session is closed. Thrown by the returned Task.