The feature that allows a client session to subscribe to topics to receive streamed topic updates and/or fetch the state of topics. More...

Inheritance diagram for PushTechnology.ClientInterface.Client.Features.ITopics:

Public Member Functions
void	AddTopicStream (ITopicSelector selector, ITopicStream stream)
	Adds a topic stream to receive topic updates for topics that match the given ITopicSelector. More...

void	AddTopicStream (string topics, ITopicStream stream)
	Adds a topic stream to receive topic events for all topics that match the given ITopicSelector expression. More...

void	AddStream< TValue > (ITopicSelector selector, IValueStream< TValue > stream)
	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. More...

void	AddStream< TValue > (string topics, IValueStream< TValue > stream)
	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. More...

void	AddFallbackTopicStream (ITopicStream stream)
	Adds a fallback topic stream. More...

void	AddFallbackStream< TValue > (IValueStream< TValue > stream)
	Adds a fallback value stream. More...

void	AddTimeSeriesStream< TValue > (ITopicSelector selector, IValueStream< IEvent< TValue >> stream)
	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. More...

void	AddTimeSeriesStream< TValue > (string topics, IValueStream< IEvent< TValue >> stream)
	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. More...

void	RemoveStream (Callbacks.IStream stream)
	Removes a stream. More...

Task< object >	SubscribeAsync (ITopicSelector selector)
	Requests subscription to topics. More...

Task< object >	SubscribeAsync (ITopicSelector selector, CancellationToken cancellationToken)
	Requests subscription to topics. More...

Task< object >	SubscribeAsync (string topics)
	Requests subscription to topics. More...

Task< object >	SubscribeAsync (string topics, CancellationToken cancellationToken)
	Requests subscription to topics. More...

void	Subscribe (ITopicSelector selector, ITopicsCompletionCallback callback)
	Requests subscription to topics. More...

void	Subscribe (string topics, ITopicsCompletionCallback callback)
	Requests subscription to topics. More...

void	Subscribe< TContext > (ITopicSelector selector, TContext context, ITopicsCompletionContextCallback< TContext > callback)
	Requests subscription to topics. More...

void	Subscribe< TContext > (string topics, TContext context, ITopicsCompletionContextCallback< TContext > callback)
	Requests subscription to topics. More...

Task< object >	UnsubscribeAsync (ITopicSelector selector)
	Unsubscribes from topics. More...

Task< object >	UnsubscribeAsync (ITopicSelector selector, CancellationToken cancellationToken)
	Unsubscribes from topics. More...

Task< object >	UnsubscribeAsync (string topics)
	Unsubscribes from topics. More...

Task< object >	UnsubscribeAsync (string topics, CancellationToken cancellationToken)
	Unsubscribes from topics. More...

void	Unsubscribe (ITopicSelector selector, ITopicsCompletionCallback callback)
	Unsubscribes from topics. More...

void	Unsubscribe (string topics, ITopicsCompletionCallback callback)
	Unsubscribes from topics. More...

void	Unsubscribe< TContext > (ITopicSelector selector, TContext context, ITopicsCompletionContextCallback< TContext > callback)
	Unsubscribes from topics. More...

void	Unsubscribe< TContext > (string topics, TContext context, ITopicsCompletionContextCallback< TContext > callback)
	Unsubscribes from topics. More...

void	Fetch (ITopicSelector selector, IFetchStream stream)
	Fetches the current state of topics. More...

void	Fetch (string topics, IFetchStream stream)
	Fetches the current state of topics. More...

void	Fetch< TContext > (ITopicSelector selector, TContext context, IFetchContextStream< TContext > stream)
	Fetches the current state of topics. More...

void	Fetch< TContext > (string topics, TContext context, IFetchContextStream< TContext > stream)
	Fetches the current state of topics. More...

void	GetTopicDetails (string topicPath, TopicDetailsLevel level, ITopicDetailsCallback callback)
	Gets the details of a given topic. More...

void	GetTopicDetails< TContext > (string topicPath, TopicDetailsLevel level, TContext context, ITopicDetailsContextCallback< TContext > callback)
	Gets the details of a given topic. 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

The feature that allows a client session to subscribe to topics to receive streamed topic updates and/or fetch the state of topics.

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).
Retrieve details of topics - such as their metadata.

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. Topic selectors are used on subscription to match against topics at the server. The session will become subscribed to any topics that exist at the server that match the selector (unless they are already subscribed, or the session has insufficient permission). The subscription request is also retained at the server so that if any newly created topics match the selector, the session will then become subscribed to it (unless a subsequent unsubscription cancels it).

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.

When a stream is added it will immediately be notified of any topics that are already subscribed to that would be selected for the stream. For certain topic types (TopicType.JSON, TopicType.BINARY, and TopicType.SINGLE_VALUE) the subscription notification will be followed by the latest known value. Other topic types do not support the local caching of values. To ensure that a value is received first, streams must be added before subscription.

A session can request unsubscription from a topic or topics at any time. This is also specified using topic selectors. On unsubscription, matching streams will be notified via the OnUnsubscription notification. This notification will give the reason for unsubscription (i.e. by request of 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 subscription control feature, or by a publisher component hosted on the server. The removal of a topic also automatically causes unsubscription for subscribed sessions.

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

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 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 data 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 be only notified of the event once. The mapping of topic selectors to streams is maintained locally in the client process.

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

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} or AddFallbackTopicStream. 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.

There are two types of subscription stream, value streams and topic streams as outlined below:

Value streams

A Topics.IValueStream{TValue} will receive values for matching topics as and when updates are received from the server. Value streams are typed to a specified value type and only values for topics that maintain locally cached values matching the type will be routed to the stream. Delta updates from the server are automatically applied to locally cached values so that the stream always receives values.

This is the preferred stream type as it is the simplest to use; however, it is not supported for all topic types. The following table shows how the value class specified when adding the stream maps to actual topic types that will be routed to the stream:

Value Type	Topic Types
Data.JSON.IJSON	TopicType.JSON
Data.Binary.IBinary	TopicType.BINARY
Data.IBytes	TopicType.SINGLE_VALUE Data.JSON.IJSON Data.Binary.IBinary
IContent	TopicType.SINGLE_VALUE Data.JSON.IJSON Data.Binary.IBinary

One or more such stream implementations can be added using AddStream{TValue}(string,IValueStream{TValue}).

Topic streams

A ITopicStream will receive both value and delta updates for all topic types.

The server initially sends the current value of a topic when a session subscribes to the topic but after that, if it is more efficient to do so, the server will just send the changes (deltas). This type of stream provides the value and the deltas but relies upon the application to apply the deltas to a session-maintained current value. A topic stream is therefore not as convenient as a Topics.IValueStream{TValue} but is currently the only option available for TopicType.RECORD and TopicType.STATELESS topics, both of which are deprecated. Topic streams will be removed along with these topic types in a future release.

One or more such stream implementations can be added using AddTopicStream(string,ITopicStream).

Fetch

A session can issue a request to fetch the state of a topic or topics (subject to authorization) at any time. Fetch requests use ITopicSelector to select the topics to fetch and because such a request could result in the fetching of many topics, a IFetchStream type callback is used. IFetchStream.OnFetchReply will be called for each selected topic that has a value.

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

Access control

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

The TopicPermission.READ_TOPIC permission is required to retrieve the topic details.

No access control restrictions are applied to unsubscription.

Since 5.0

This example shows how to access the topics feature from a Session.ISession and subscribe to a JSON topic.

// Accessing the feature.
var topics = session.Topics;
// Add a JSON fallback stream
topics.AddFallbackStream&lt;IJSON&gt;( myFallbackStream );
// Subscribing to a topic and waiting for the operation to finish.
// This operation will block until the subscription
// operation has been finished.
topics.SubscribeAsync( "myTopic" ).Wait();
// Subscribing in a async/await scenario.
await topics.SubscribeAsync( "myTopic" );
// Unsubscription from a topic works in the same way
// as subscription. Simply use UnsubscribeAsync() instead.
await topics.UnsubscribeAsync( "myTopic" );
// The await/async pattern is the preferred way to
// use the ITopics feature. For more information, visit:
// https://msdn.microsoft.com/en-gb/library/mt674882.aspx

Member Function Documentation

void PushTechnology.ClientInterface.Client.Features.ITopics.AddFallbackStream< TValue > ( IValueStream< TValue > stream )

Adds a fallback value stream.

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

Since 5.7

Template Parameters

TValue The value type.

Parameters

stream The stream to add.

Exceptions

System.ArgumentNullException The stream is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.AddFallbackTopicStream ( ITopicStream stream )

Adds a fallback topic stream.

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

Since 5.1

Parameters

stream The topic stream to add as a fallback stream.

Exceptions

System.ArgumentNullException The stream is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.AddStream< TValue >	(	ITopicSelector	selector,
		IValueStream< TValue >	stream
	)

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.

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

Since 5.7

Template Parameters

TValue The value type.

Parameters

selector	The selector of one or more topics.
stream	The stream to add.

Exceptions

System.ArgumentNullException The selector or stream is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.AddStream< TValue >	(	string	topics,
		IValueStream< TValue >	stream
	)

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.

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

Since 5.7

Template Parameters

TValue The value type.

Parameters

topics	The topics as a ITopicSelector expression.
stream	The stream to add.

Exceptions

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

void PushTechnology.ClientInterface.Client.Features.ITopics.AddTimeSeriesStream< TValue >	(	ITopicSelector	selector,
		IValueStream< IEvent< TValue >>	stream
	)

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.

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(Callbacks.IStream).

Added in version 6.1.

Template Parameters

TValue The time series value type.

Parameters

selector	The ITopicSelector.
stream	The time series value stream.

Exceptions

ArgumentNullException The selector or stream is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.AddTimeSeriesStream< TValue >	(	string	topics,
		IValueStream< IEvent< TValue >>	stream
	)

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.

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(Callbacks.IStream).

Added in version 6.1.

Template Parameters

TValue The time series value type.

Parameters

topics	The ITopicSelector expression.
stream	The time series value stream.

Exceptions

ArgumentNullException	The topics expression or stream is `null`.
ArgumentException	The topics expression is not a valid selector expression.

void PushTechnology.ClientInterface.Client.Features.ITopics.AddTopicStream	(	ITopicSelector	selector,
		ITopicStream	stream
	)

Adds a topic stream to receive topic updates for topics that match the given ITopicSelector.

Since 5.1

Parameters

selector	The selector of one or more topics.
stream	The topic stream to add.

Exceptions

System.ArgumentNullException The selector or stream is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.AddTopicStream	(	string	topics,
		ITopicStream	stream
	)

Adds a topic stream to receive topic events for all topics that match the given ITopicSelector expression.

This is equivalent to calling AddTopicStream(ITopicSelector,ITopicStream) with a selector parsed from the given string expression.

Since 5.1

Parameters

topics	The topics as a ITopicSelector expression.
stream	The topic stream to add.

Exceptions

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

void PushTechnology.ClientInterface.Client.Features.ITopics.Fetch	(	ITopicSelector	selector,
		IFetchStream	stream
	)

Fetches the current state of topics.

The fetch stream's IFetchStream.OnFetchReply(string, IContent) method will be called for each topic that matches the selector for which a fetch request can be satisfied, followed by IFetchStream.OnClose().

Since 5.0

Parameters

selector	The topics to fetch.
stream	The stream object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException The selector or stream is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.Fetch	(	string	topics,
		IFetchStream	stream
	)

Fetches the current state of topics.

This is equivalent to calling Fetch(ITopicSelector,IFetchStream) with a selector parsed from the given string expression.

Since 5.0

Parameters

topics	The ITopicSelector expression specifying the topics to fetch.
stream	The stream object to receive status notifications for this operation.

Exceptions

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

void PushTechnology.ClientInterface.Client.Features.ITopics.Fetch< TContext >	(	ITopicSelector	selector,
		TContext	context,
		IFetchContextStream< TContext >	stream
	)

Fetches the current state of topics.

The fetch stream's IFetchContextStream{TContext}.OnFetchReply(TContext, string, IContent) method will be called for each topic that matches the selector for which a fetch request can be satisfied, followed by IFetchContextStream{TContext}.OnClose(TContext).

Since 5.0

Template Parameters

TContext The context object type.

Parameters

selector	The topics to fetch.
context	The object passed to the stream with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including 'null'.
stream	The callback stream to receive status notifications for this operation.

Exceptions

System.ArgumentNullException The selector or stream is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.Fetch< TContext >	(	string	topics,
		TContext	context,
		IFetchContextStream< TContext >	stream
	)

Fetches the current state of topics.

This is equivalent to calling Fetch{TContext}(ITopicSelector,TContext,IFetchContextStream{TContext}) with a selector parsed from the given string expression.

Since 5.0

Template Parameters

TContext The context object type.

Parameters

topics	The ITopicSelector expression specifying the topics to fetch.
context	The object passed to the stream with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including 'null'.
stream	The stream object to receive status notifications for this operation.

Exceptions

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

void PushTechnology.ClientInterface.Client.Features.ITopics.GetTopicDetails	(	string	topicPath,
		TopicDetailsLevel	level,
		ITopicDetailsCallback	callback
	)

Gets the details of a given topic.

The ITopicDetailsCallback.OnTopicDetails(string,ITopicDetails) callback method will be called with the result.

Since 5.0

Parameters

topicPath	The full path of the topic.
level	The required level of detail.
callback	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException The topicPath , level or callback is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.GetTopicDetails< TContext >	(	string	topicPath,
		TopicDetailsLevel	level,
		TContext	context,
		ITopicDetailsContextCallback< TContext >	callback
	)

Gets the details of a given topic.

The ITopicDetailsContextCallback{TContext}.OnTopicDetails(TContext,string,ITopicDetails) callback method will be called with the result.

Since 5.0

Template Parameters

TContext The context object type.

Parameters

topicPath	The full path of the topic.
level	The required level of detail.
context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including 'null'.
callback	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException The topicPath , level or callback is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.RemoveStream ( Callbacks.IStream stream )

Removes a stream.

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.

Since 5.7

Parameters

stream The value stream to remove.

Exceptions

System.ArgumentNullException The stream is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.Subscribe	(	ITopicSelector	selector,
		ITopicsCompletionCallback	callback
	)

Requests subscription to topics.

Since 5.0

Parameters

selector	The topics to subscribe to.
callback	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException The selector or callback is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.Subscribe	(	string	topics,
		ITopicsCompletionCallback	callback
	)

Requests subscription to topics.

This is equivalent to calling Subscribe(ITopicSelector,ITopicsCompletionCallback) with a selector parsed from the given string expression.

Since 5.0

Parameters

topics	The ITopicSelector expression specifying the topics to request subscription to.
callback	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException	The topics expression or callback is `null`.
System.ArgumentException	The topics expression is not a valid selector expression.

void PushTechnology.ClientInterface.Client.Features.ITopics.Subscribe< TContext >	(	ITopicSelector	selector,
		TContext	context,
		ITopicsCompletionContextCallback< TContext >	callback
	)

Requests subscription to topics.

Since 5.0

Template Parameters

TContext The context object type.

Parameters

selector	The topics to subscribe to.
context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including 'null'.
callback	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException The selector or callback is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.Subscribe< TContext >	(	string	topics,
		TContext	context,
		ITopicsCompletionContextCallback< TContext >	callback
	)

Requests subscription to topics.

This is equivalent to calling Subscribe{TContext}(ITopicSelector,TContext,ITopicsCompletionContextCallback{TContext}) with a selector parsed from the given string expression.

Since 5.0

Template Parameters

TContext The context object type.

Parameters

topics	The ITopicSelector expression specifying the topics to request subscription to.
context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including 'null'.
callback	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException	The topics expression or callback is `null`.
System.ArgumentException	The topics expression is not a valid selector expression.

Task<object> PushTechnology.ClientInterface.Client.Features.ITopics.SubscribeAsync ( ITopicSelector selector )

Requests subscription to topics.

If the task completes successfully, the Task result will be null. The result type is Task{object} rather than Task to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

Since 6.0

Parameters

selector The topics to subscribe to.

Returns: The task representing the current operation.

Exceptions

System.ArgumentNullException	The selector is `null`.
Session.SessionClosedException	The session is closed. Thrown by the returned task.
Session.SessionSecurityException	The calling session does not have TopicPermission.SELECT_TOPIC permissions for the path prefix of the given selector. Thrown by the returned task.

See Also: SubscribeAsync(ITopicSelector, CancellationToken)

Task<object> PushTechnology.ClientInterface.Client.Features.ITopics.SubscribeAsync	(	ITopicSelector	selector,
		CancellationToken	cancellationToken
	)

Requests subscription to topics.

If the task completes successfully, the Task result will be null. The result type is Task{object} rather than Task to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

Since 6.0

Parameters

selector	The topics to subscribe to.
cancellationToken	The cancellation token used to cancel the current operation.

Returns: The task representing the current operation.

Exceptions

System.ArgumentNullException	The selector is `null`.
Session.SessionClosedException	The session is closed. Thrown by the returned task.
Session.SessionSecurityException	The calling session does not have TopicPermission.SELECT_TOPIC permissions for the path prefix of the given selector. Thrown by the returned task.

Subscribing to a topic

try {
    var src = new CancellationTokenSource();
    await session.Topics.SubscribeAsync(
        Diffusion.TopicSelectors.Parse( "myTopic" ), src.Token );
} catch ( SessionClosedException ex ) {
    Console.WriteLine( $"Subscription failed. Reason: {ex}." );
} catch ( SessionSecurityException ex ) {
    Console.WriteLine( $"Subscription failed. Reason: {ex}." );
}

Task<object> PushTechnology.ClientInterface.Client.Features.ITopics.SubscribeAsync ( string topics )

Requests subscription to topics.

If the task completes successfully, the Task result will be null. The result type is Task{object} rather than Task to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

Since 6.0

Parameters

topics The ITopicSelector expression specifying the topics to request subscription to.

Returns: The task representing the current operation.

Exceptions

System.ArgumentNullException	The topics expression is `null`.
System.ArgumentException	The topics expression is not a valid selector expression.
Session.SessionClosedException	The session is closed. Thrown by the returned task.
Session.SessionSecurityException	The calling session does not have TopicPermission.SELECT_TOPIC permissions for the path prefix of the given selector expression. Thrown by the returned task.

See Also: SubscribeAsync(string, CancellationToken)

Task<object> PushTechnology.ClientInterface.Client.Features.ITopics.SubscribeAsync	(	string	topics,
		CancellationToken	cancellationToken
	)

Requests subscription to topics.

If the task completes successfully, the Task result will be null. The result type is Task{object} rather than Task to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

Since 6.0

Parameters

topics	The ITopicSelector expression specifying the topics to request subscription to.
cancellationToken	The cancellation token used to cancel the current operation.

Returns: The task representing the current operation.

Exceptions

System.ArgumentNullException	The topics expression is `null`.
System.ArgumentException	The topics expression is not a valid selector expression.
Session.SessionClosedException	The session is closed. Thrown by the returned task.
Session.SessionSecurityException	The calling session does not have TopicPermission.SELECT_TOPIC permissions for the path prefix of the given selector expression. Thrown by the returned task.

Subscribing to a topic

try {
    var src = new CancellationTokenSource();
    await session.Topics.SubscribeAsync( "myTopic", src.Token );
} catch ( SessionClosedException ex ) {
    Console.WriteLine( $"Subscription failed. Reason: {ex}." );
} catch ( SessionSecurityException ex ) {
    Console.WriteLine( $"Subscription failed. Reason: {ex}." );
}

void PushTechnology.ClientInterface.Client.Features.ITopics.Unsubscribe	(	ITopicSelector	selector,
		ITopicsCompletionCallback	callback
	)

Unsubscribes from topics.

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.

Since 5.0

Parameters

selector	The topics to unsubscribe from.
callback	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException The selector or callback is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.Unsubscribe	(	string	topics,
		ITopicsCompletionCallback	callback
	)

Unsubscribes from topics.

This is equivalent to calling Unsubscribe(ITopicSelector,ITopicsCompletionCallback) with a selector parsed from the given string expression.

Since 5.0

Parameters

topics	The ITopicSelector expression specifying the topics to unsubscribe from.
callback	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException	The topics expression or callback is `null`.
System.ArgumentException	The topics expression is not a valid selector expression.

void PushTechnology.ClientInterface.Client.Features.ITopics.Unsubscribe< TContext >	(	ITopicSelector	selector,
		TContext	context,
		ITopicsCompletionContextCallback< TContext >	callback
	)

Unsubscribes from topics.

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.

Since 5.0

Template Parameters

TContext The context object type.

Parameters

selector	The topics to unsubscribe from.
context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including 'null'.
callback	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException The selector or callback is null.

void PushTechnology.ClientInterface.Client.Features.ITopics.Unsubscribe< TContext >	(	string	topics,
		TContext	context,
		ITopicsCompletionContextCallback< TContext >	callback
	)

Unsubscribes from topics.

This is equivalent to calling Unsubscribe{TContext}(ITopicSelector,TContext,ITopicsCompletionContextCallback{TContext}) with a selector parsed from the given string expression.

Since 5.0

Template Parameters

TContext The context object type.

Parameters

topics	The ITopicSelector expression specifying the topics to unsubscribe from.
context	The object passed to the callback with the reply to allow requests and replies to be correlated. The caller can use any convenient object reference, including 'null'.
callback	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException	The topics expression or callback is `null`.
System.ArgumentException	The topics expression is not a valid selector expression.

Task<object> PushTechnology.ClientInterface.Client.Features.ITopics.UnsubscribeAsync ( ITopicSelector selector )

Unsubscribes from topics.

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. The result type is Task{object} rather than Task to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

Since 6.0

Parameters

selector The topics to unsubscribe from.

Returns: The task representing the current operation.

Exceptions

System.ArgumentNullException	The selector is `null`.
Session.SessionClosedException	The session is closed. Thrown by the returned task.

See Also: UnsubscribeAsync(ITopicSelector, CancellationToken)

Task<object> PushTechnology.ClientInterface.Client.Features.ITopics.UnsubscribeAsync	(	ITopicSelector	selector,
		CancellationToken	cancellationToken
	)

Unsubscribes from topics.

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. The result type is Task{object} rather than Task to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

Since 6.0

Parameters

selector	The topics to unsubscribe from.
cancellationToken	The cancellation token used to cancel the current operation.

Returns: The task representing the current operation.

Exceptions

System.ArgumentNullException	The selector is `null`.
Session.SessionClosedException	The session is closed. Thrown by the returned task.

Unsubscribing from a topic

try {
    var src = new CancellationTokenSource();
    await session.Topics.UnsubscribeAsync(
        Diffusion.TopicSelectors.Parse( "myTopic" ), src.Token );
} catch ( SessionClosedException ex ) {
    Console.WriteLine( $"Subscription failed. Reason: {ex}." );
}

Task<object> PushTechnology.ClientInterface.Client.Features.ITopics.UnsubscribeAsync ( string topics )

Unsubscribes from topics.

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. The result type is Task{object} rather than Task to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

Since 6.0

Parameters

topics The ITopicSelector expression specifying the topics to unsubscribe from.

Returns: The task representing the current operation.

Exceptions

System.ArgumentNullException	The topics expression is `null`.
System.ArgumentException	The topics expression is not a valid selector expression.
Session.SessionClosedException	The session is closed. Thrown by the returned task.

See Also: UnsubscribeAsync(string, CancellationToken)

Task<object> PushTechnology.ClientInterface.Client.Features.ITopics.UnsubscribeAsync	(	string	topics,
		CancellationToken	cancellationToken
	)

Unsubscribes from topics.

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. The result type is Task{object} rather than Task to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

Since 6.0

Parameters

topics	The ITopicSelector expression specifying the topics to unsubscribe from.
cancellationToken	The cancellation token used to cancel the current operation.

Returns: The task representing the current operation.

Exceptions

System.ArgumentNullException	The topics expression is `null`.
System.ArgumentException	The topics expression is not a valid selector expression.
Session.SessionClosedException	The session is closed. Thrown by the returned task.

Unsubscribing from a topic

try {
    var src = new CancellationTokenSource();
    await session.Topics.UnsubscribeAsync( "myTopic", src.Token );
} catch ( SessionClosedException ex ) {
    Console.WriteLine( $"Subscription failed. Reason: {ex}." );
}

The documentation for this interface was generated from the following file:

Client.Public/Features/ITopics.cs

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation