The feature that allows a session to manage topics. More...

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

Public Member Functions
ITopicSpecification	NewSpecification (TopicType topicType)
	Creates a new ITopicSpecification for a given topic type. More...

Task< AddTopicResult >	AddTopicAsync (string topicPath, TopicType topicType)
	Requests creation of a topic. More...

Task< AddTopicResult >	AddTopicAsync (string topicPath, TopicType topicType, CancellationToken cancellationToken)
	Requests creation of a topic. More...

Task< AddTopicResult >	AddTopicAsync (string topicPath, ITopicSpecification specification)
	Requests creation of a topic. More...

Task< AddTopicResult >	AddTopicAsync (string topicPath, ITopicSpecification specification, CancellationToken cancellationToken)
	Requests creation of a topic. More...

ITopicDetails	AddTopic (string topicPath, TopicType topicType, ITopicControlAddCallback callback)
	Sends a request to the server to add a topic. More...

ITopicDetails	AddTopic (string topicPath, TopicType topicType, IBytes value, ITopicControlAddCallback callback)
	Sends a request to the server to add a topic. More...

ITopicDetails	AddTopic< TContext > (string topicPath, TopicType topicType, TContext context, ITopicControlAddContextCallback< TContext > callback)
	Sends a request to the server to add a topic. More...

ITopicDetails	AddTopic< TContext > (string topicPath, TopicType topicType, IBytes value, TContext context, ITopicControlAddContextCallback< TContext > callback)
	Sends a request to the server to add a topic. More...

void	AddTopic (string topicPath, ITopicSpecification specification, ITopicControlAddCallback callback)
	Sends a request to the server to add a topic. More...

void	AddTopic (string topicPath, ITopicSpecification specification, IBytes value, ITopicControlAddCallback callback)
	Sends a request to the server to add a topic. More...

void	AddTopic< TContext > (string topicPath, ITopicSpecification specification, TContext context, ITopicControlAddContextCallback< TContext > callback)
	Sends a request to the server to add a topic. More...

void	AddTopic< TContext > (string topicPath, ITopicSpecification specification, IBytes value, TContext context, ITopicControlAddContextCallback< TContext > callback)
	Sends a request to the server to add a topic. More...

Task< object >	RemoveTopicsAsync (string topicSelector)
	Sends a request to remove one or more topics. More...

Task< object >	RemoveTopicsAsync (string topicSelector, CancellationToken cancellationToken)
	Sends a request to remove one or more topics. More...

Task< object >	RemoveTopicsAsync (ITopicSelector topicSelector)
	Sends a request to remove one or more topics. More...

Task< object >	RemoveTopicsAsync (ITopicSelector topicSelector, CancellationToken cancellationToken)
	Sends a request to remove one or more topics. More...

void	Remove (string topicSelector, ITopicControlRemovalCallback callback)
	Sends a request to remove one or more topics. More...

void	Remove< TContext > (string topicSelector, TContext context, ITopicControlRemovalContextCallback< TContext > callback)
	Sends a request to remove one or more topics. More...

Task< IRegistration >	RemoveTopicsWithSessionAsync (string topicPath)
	Register a deferred action to remove all topics that the caller has permission to remove from a branch of the topic tree. More...

Task< IRegistration >	RemoveTopicsWithSessionAsync (string topicPath, CancellationToken cancellationToken)
	Register a deferred action to remove all topics that the caller has permission to remove from a branch of the topic tree. More...

void	RemoveTopicsWithSession (string topicPath, Callbacks.ITopicTreeHandler registrationHandler)
	Register a deferred action to remove all topics that the caller has permission to remove from a branch of the topic tree. More...

Task< IRegistration >	AddMissingTopicHandlerAsync (string topicPath, IMissingTopicNotificationStream stream)
	Registers a IMissingTopicNotificationStream to handle requests for a branch of the topic tree. More...

Task< IRegistration >	AddMissingTopicHandlerAsync (string topicPath, IMissingTopicNotificationStream stream, CancellationToken cancellationToken)
	Registers a IMissingTopicNotificationStream to handle requests for a branch of the topic tree. More...

void	AddMissingTopicHandler (string topicPath, IMissingTopicHandler handler)
	Registers a IMissingTopicHandler to handle requests for a branch of the topic tree. More...

Task< IRegistration >	AddTopicEventListenerAsync (string topicPath, ITopicEventStream stream)
	Registers a ITopicEventStream to receive topic events for a branch of the topic tree. More...

Task< IRegistration >	AddTopicEventListenerAsync (string topicPath, ITopicEventStream stream, CancellationToken cancellationToken)
	Registers a ITopicEventStream to receive topic events for a branch of the topic tree. More...

void	AddTopicEventListener (string topicPath, ITopicControlTopicEventListener listener)
	Registers a ITopicControlTopicEventListener to receive topic events for a branch of the topic tree. More...

TBuilder	CreateDetailsBuilder< TBuilder > ()
	Creates a new topic details builder to create ITopicDetails of a type corresponding to the given builder type. More...

ITopicDetails	NewDetails (TopicType topicType)
	Returns new topic details of the given type set with all default settings. More...

void	AddTopic (string topicPath, ITopicDetails details, ITopicControlAddCallback callback)
	Sends a request to the server to add a topic. More...

void	AddTopic (string topicPath, ITopicDetails details, IBytes value, ITopicControlAddCallback callback)
	Sends a request to the server to add a topic. More...

void	AddTopic< TContext > (string topicPath, ITopicDetails details, TContext context, ITopicControlAddContextCallback< TContext > callback)
	Sends a request to the server to add a topic. More...

void	AddTopic< TContext > (string topicPath, ITopicDetails details, IBytes value, TContext context, ITopicControlAddContextCallback< TContext > callback)
	Sends a request to the server to add a topic. More...

ITopicDetails	AddTopicFromValue< TValue > (string topicPath, TValue value, ITopicControlAddCallback callback)
	Sends a request to the server to add a topic where the type and initial value for the topic are derived from a provided value object. More...

ITopicDetails	AddTopicFromValue< TValue, TContext > (string topicPath, TValue value, TContext context, ITopicControlAddContextCallback< TContext > callback)
	Sends a request to the server to add a topic where the type and initial value for the topic are derived from a provided value object. 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 session to manage topics.

This feature provides the following capabilities:

Adding and removing topics.
Missing topic notifications — listening for requests to subscribe to (or fetch) topics that do not exist thus allowing dynamic topic creation on demand.
Topic event listeners — listening for topic events, such as the changing number of subscribers to a topic.

Topics

The Diffusion server stores data in topics. Each topic is bound to a topic path in the topic tree, and may have a current value. Sessions can subscribe to topics. Updates to topic values are broadcast to subscribing sessions. There are several types of topic. The TopicType determines the type of the data values a topic publishes to subscribers.

Creating topics

The simplest way to create a topic is to call AddTopicAsync(string,TopicType), supplying the topic path and topic type.

Success or failure is reported asynchronously through the returned Task.

The nature of a topic depends primarily on its topic type, but can be customized using topic properties. Some types of topic cannot be created without supplying mandatory topic properties. Topic properties can be supplied via a ITopicSpecification implementation using AddTopicAsync(string,ITopicSpecification). Topic specifications can be created using NewSpecification(TopicType) and further customized with builder methods.

See TopicSpecificationProperty for details of the available topic properties and their effects on the different types of topic.

There are further variants of these methods that allow an initial value to be supplied for the topic. If a topic is created without an initial value, TopicType.SINGLE_VALUE and TopicType.RECORD topic types will assume a default initial value, whereas others will simply not have an initial value.

Topic creation is idempotent. If AddTopicAsync(string,ITopicSpecification) is called and there is already a topic bound to the given path with a topic specification equal to the one provided, the Task will complete successfully with AddTopicResult.EXISTS. However, if there is a topic bound to the given topic path with a different topic specification, the returned task will complete exceptionally with a ExistingTopicException.

Creating record topics

The TopicType.RECORD topic type and ITopicDetails have both been deprecated in this release. Prefer the TopicType.RECORD_V2 topic type, which can be created using a topic specification as described above.

This feature also provides methods to create topics from ITopicDetails — a more involved way to define a topic that pre-dates topic specifications. For all types of topic except for record topics, using a topic specification as described above is simpler and to be preferred.

Practically, record topics must be created with IRecordTopicDetails, not a topic specification, so useful metadata can be provided. If a record topic is created from a topic specification, it will have default metadata which describes a single record with a single variable multiplicity field.

To create a ITopicDetails instance, use a ITopicDetailsBuilder of the correct type. After setting properties as required on the builder, it can be used to build immutable ITopicDetails which can then be used to add topics via AddTopic(string,ITopicDetails,ITopicControlAddCallback).

If many topics are to be created with the same definition, re-use the same details instance as the feature is optimized to only transmit the details to the server once in this situation.

Removing topics

Topics can be removed using RemoveTopicsAsync(ITopicSelector). If a topic is selected but the caller does not have TopicPermission.MODIFY_TOPIC permission to it, the topic will remain.

Topics can also be automatically removed according to a removal criteria specified using the TopicSpecificationProperty.Removal topic property.

From 6.0, topics created using the Publisher API cannot be removed using this feature.

Managing topic tree hierarchies

A topic can be bound to any path in the topic tree namespace. The only restriction is that two topics can not have the same path. In general, topics can be created in any order. A TopicType.SLAVE topic can only be created if its master topic already exists.

A topic can be created with the path "A/B/foo" even though there are no topics with path "A" or "A/B". Topics bound to the paths "A" or "A/B" can be created later.

Topics can be removed without affecting the topics subordinate to them in the topic tree using RemoveTopicsAsync(string) providing a path topic selector. By using the "//" topic selector qualifier it is possible to remove a topic and all of its descendant topics, that is to remove whole topic tree branches.

Access control

To add or remove a topic, a session needs TopicPermission.MODIFY_TOPIC permission for the topic path. When removing topics with a topic selector that matches more than one topic, only topics with paths for which the session has TopicPermission.MODIFY_TOPIC permission will be removed.

To register a AddMissingTopicHandlerAsync(string, IMissingTopicNotificationStream) or a AddTopicEventListenerAsync(string, ITopicEventStream) the session needs GlobalPermission.REGISTER_HANDLER permission.

Since 5.0

This example shows how to access the topics feature from a ISession.

// Accessing the feature.

var topicControl = session.TopicControl;

Member Function Documentation

void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddMissingTopicHandler	(	string	topicPath,
		IMissingTopicHandler	handler
	)

Registers a IMissingTopicHandler to handle requests for a branch of the topic tree.

The provided handler is called when a session subscribes or fetches using a topic selector that matches no existing topics. This allows a control client session to intercede when another session requests a topic that does not exist. The control client may use any of the AddTopic methods to create the topic, take some other action, or do nothing, before allowing the client operation to proceed by calling IMissingTopicNotification.Proceed. Alternatively, the control client can call IMissingTopicNotification.Cancel to discard the request.

A session can register multiple handlers, but may only register a single handler for a given topic path. See ITopicTreeHandler.OnActive(string, IRegisteredHandler). A handler will only be called for topic selectors with a path prefix that starts with or is equal to the given topicPath . If the path prefix matches multiple handlers, the one registered for the most specific (longest) topic path will be called.

Parameters

topicPath	The branch of the topic tree.
handler	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException The topicPath , or handler is null.

Task<IRegistration> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddMissingTopicHandlerAsync	(	string	topicPath,
		IMissingTopicNotificationStream	stream
	)

Registers a IMissingTopicNotificationStream to handle requests for a branch of the topic tree.

The provided handler is called when a session subscribes or fetches using a topic selector that matches no existing topics. This allows a control client session to intercede when another session requests a topic that does not exist. The control client may use any of the AddTopic methods to create the topic, take some other action, or do nothing, before allowing the client operation to proceed by calling IMissingTopicNotification.Proceed. Alternatively, the control client can call IMissingTopicNotification.Cancel to discard the request.

A session can register multiple handlers, but may only register a single handler for a given topic path. If there is already a handler registered for the topic path the operation will fail with a HandlerConflictException. A handler will only be called for topic selectors with a ITopicSelector.PathPrefix that starts with or is equal to topicPath . If the path prefix matches multiple handlers, the one registered for the most specific (longest) topic path will be called.

If registration was successful, the Task will complete successfully with a IRegistration which can be used to unregister the stream.

Since 6.0

Parameters

topicPath	The branch of the topic tree.
stream	The stream to use for routing topics at or below the topicPath (unless there is a stream registered for a more specific topic path).

Returns: The task representing the current operation.

Exceptions

ArgumentNullException	The topicPath or stream is `null`.
SessionClosedException	The session is closed. Thrown by the returned task.
SessionSecurityException	The calling session does not have GlobalPermission.REGISTER_HANDLER permissions. Thrown by the returned task.
HandlerConflictException	The session has already registered a missing topic handler for topicPath . Thrown by the returned task.

See Also: AddMissingTopicHandlerAsync(string, IMissingTopicNotificationStream, CancellationToken)

Task<IRegistration> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddMissingTopicHandlerAsync	(	string	topicPath,
		IMissingTopicNotificationStream	stream,
		CancellationToken	cancellationToken
	)

Registers a IMissingTopicNotificationStream to handle requests for a branch of the topic tree.

The provided handler is called when a session subscribes or fetches using a topic selector that matches no existing topics. This allows a control client session to intercede when another session requests a topic that does not exist. The control client may use any of the AddTopic methods to create the topic, take some other action, or do nothing, before allowing the client operation to proceed by calling IMissingTopicNotification.Proceed. Alternatively, the control client can call IMissingTopicNotification.Cancel to discard the request.

A session can register multiple handlers, but may only register a single handler for a given topic path. If there is already a handler registered for the topic path the operation will fail with a HandlerConflictException. A handler will only be called for topic selectors with a ITopicSelector.PathPrefix that starts with or is equal to topicPath . If the path prefix matches multiple handlers, the one registered for the most specific (longest) topic path will be called.

If registration was successful, the Task will complete successfully with a IRegistration which can be used to unregister the stream.

Since 6.0

Parameters

topicPath	The branch of the topic tree.
stream	The stream to use for routing topics at or below the topicPath (unless there is a stream registered for a more specific topic path).
cancellationToken	The cancellation token used to cancel the current operation.

Returns: The task representing the current operation.

Exceptions

ArgumentNullException	The topicPath or stream is `null`.
SessionClosedException	The session is closed. Thrown by the returned task.
SessionSecurityException	The calling session does not have GlobalPermission.REGISTER_HANDLER permissions. Thrown by the returned task.
HandlerConflictException	The session has already registered a missing topic handler for topicPath . Thrown by the returned task.

ITopicDetails PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopic	(	string	topicPath,
		TopicType	topicType,
		ITopicControlAddCallback	callback
	)

Sends a request to the server to add a topic.

This is a convenience method which is equivalent to a call to AddTopic(string,ITopicSpecification,ITopicControlAddCallback) with the specification generated from NewSpecification(TopicType).

Parameters

topicPath	The topic path to which the topic will be bound.
topicType	The type of topic to be created.
callback	The callback object to receive status notifications for this operation.

Returns: The details used to add the topic. Can be used to pass to other AddTopic calls.

Exceptions

System.ArgumentNullException	The topicPath , topicType , or callback is `null`.
System.ArgumentException	The topicType is invalid (eg. stateless topic).

ITopicDetails PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopic	(	string	topicPath,
		TopicType	topicType,
		IBytes	value,
		ITopicControlAddCallback	callback
	)

Sends a request to the server to add a topic.

This is a convenience method which is equivalent to a call to AddTopic(string,ITopicSpecification,IBytes,ITopicControlAddCallback) with the specification generated from NewSpecification(TopicType).

If the given value is null this call has the same effect as calling AddTopic(string,TopicType,ITopicControlAddCallback). A value can only be supplied for a topic type that maintains state.

Parameters

topicPath	The topic path to which the topic will be bound.
topicType	The type of topic to be created.
value	The initial value.
callback	The callback object to receive status notifications for this operation.

Returns: The details used to add the topic. Can be used to pass to other AddTopic calls.

Exceptions

System.ArgumentNullException	The topicPath , topicType , or callback is `null`.
System.ArgumentException	The topicType is invalid (eg. stateless topic).

void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopic	(	string	topicPath,
		ITopicSpecification	specification,
		ITopicControlAddCallback	callback
	)

Sends a request to the server to add a topic.

A sepcification can be created with NewSpecification(TopicType).

Since 5.8

Parameters

topicPath	The topic path to which the topic will be bound.
specification	The topic specifications of the topic to be created.
callback	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException	The topicPath , specification , or callback is `null`.
System.ArgumentException	The specification is invalid (eg. stateless topic).

void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopic	(	string	topicPath,
		ITopicSpecification	specification,
		IBytes	value,
		ITopicControlAddCallback	callback
	)

Sends a request to the server to add a topic.

The topic will be initialized with the given value during creation and therefore the value must be compatible with the TopicType. Otherwise, an TopicAddFailReason.INITIALISE_ERROR will be returned.

If the given value is null this call has the same effect as calling AddTopic(string,ITopicSpecification,ITopicControlAddCallback). A value can only be supplied for a topic type that maintains state.

A sepcification can be created with NewSpecification(TopicType).

Since 5.8

Parameters

topicPath	The topic path to which the topic will be bound.
specification	The topic specifications of the topic to be created.
value	The initial value.
callback	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException	The topicPath , specification , or callback is `null`.
System.ArgumentException	The specification is invalid (eg. stateless topic).

void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopic	(	string	topicPath,
		ITopicDetails	details,
		ITopicControlAddCallback	callback
	)

Sends a request to the server to add a topic.

Parameters

topicPath	The topic path to which the topic will be bound.
details	The details of the topic to be created.
callback	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException	The topicPath , details , or callback is `null`.
System.ArgumentException	The details are invalid (eg. custom implementation or stateless topic).

void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopic	(	string	topicPath,
		ITopicDetails	details,
		IBytes	value,
		ITopicControlAddCallback	callback
	)

Sends a request to the server to add a topic.

The topic will be initialized with the given value during creation and therefore the value must be compatible with the TopicType. Otherwise, an TopicAddFailReason.INITIALISE_ERROR will be returned.

If the given value is null this call has the same effect as calling AddTopic(string,ITopicDetails,ITopicControlAddCallback). A value can only be supplied for a topic type that maintains state.

Parameters

topicPath	The topic path to which the topic will be bound.
details	The details of the topic to be created.
value	The initial value.
callback	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException	The topicPath , details , or callback is `null`.
System.ArgumentException	The details are invalid (eg. custom implementation or stateless topic).

ITopicDetails PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopic< TContext >	(	string	topicPath,
		TopicType	topicType,
		TContext	context,
		ITopicControlAddContextCallback< TContext >	callback
	)

Sends a request to the server to add a topic.

Template Parameters

TContext The context object type.

Parameters

topicPath	The topic path to which the topic will be bound.
topicType	The type of topic to be created.
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.

Returns: The details used to add the topic. Can be used to pass to other AddTopic calls.

Exceptions

System.ArgumentNullException	The topicPath , topicType , or callback is `null`.
System.ArgumentException	The topicType is invalid (eg. stateless topic).

ITopicDetails PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopic< TContext >	(	string	topicPath,
		TopicType	topicType,
		IBytes	value,
		TContext	context,
		ITopicControlAddContextCallback< TContext >	callback
	)

Sends a request to the server to add a topic.

If the given value is null this call has the same effect as calling AddTopic{TContext}(string,TopicType,TContext,ITopicControlAddContextCallback{TContext}). A value can only be supplied for a topic type that maintains state.

Template Parameters

TContext The context type.

Parameters

topicPath	The topic path to which the topic will be bound.
topicType	The type of topic to be created.
value	The initial value.
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.

Returns: The details used to add the topic. Can be used to pass to other AddTopic calls.

Exceptions

System.ArgumentNullException	The topicPath , topicType , or callback is `null`.
System.ArgumentException	The topicType is invalid (eg. stateless topic).

void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopic< TContext >	(	string	topicPath,
		ITopicSpecification	specification,
		TContext	context,
		ITopicControlAddContextCallback< TContext >	callback
	)

Sends a request to the server to add a topic.

A sepcification can be created with NewSpecification(TopicType).

Since 5.8

Template Parameters

TContext The context type.

Parameters

topicPath	The topic path to which the topic will be bound.
specification	The topic specifications of the topic to be created.
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 , specification , or callback is `null`.
System.ArgumentException	The specification is invalid (eg. stateless topic).

void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopic< TContext >	(	string	topicPath,
		ITopicSpecification	specification,
		IBytes	value,
		TContext	context,
		ITopicControlAddContextCallback< TContext >	callback
	)

Sends a request to the server to add a topic.

The topic will be initialized with the given value during creation and therefore the value must be compatible with the TopicType. Otherwise, an TopicAddFailReason.INITIALISE_ERROR will be returned.

If the given value is null this call has the same effect as calling AddTopic{TContext}(string,ITopicSpecification,TContext,ITopicControlAddContextCallback{TContext}). A value can only be supplied for a topic type that maintains state.

A sepcification can be created with NewSpecification(TopicType).

Since 5.8

Template Parameters

TContext The context type.

Parameters

topicPath	The topic path to which the topic will be bound.
specification	The topic specifications of the topic to be created.
value	The initial value.
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 , specification , or callback is `null`.
System.ArgumentException	The specification is invalid (eg. stateless topic).

void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopic< TContext >	(	string	topicPath,
		ITopicDetails	details,
		TContext	context,
		ITopicControlAddContextCallback< TContext >	callback
	)

Sends a request to the server to add a topic.

Template Parameters

TContext The context type.

Parameters

topicPath	The topic path to which the topic will be bound.
details	The details of the topic to be created.
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 , details , or callback is `null`.
System.ArgumentException	The details are invalid (eg. custom implementation or stateless topic).

void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopic< TContext >	(	string	topicPath,
		ITopicDetails	details,
		IBytes	value,
		TContext	context,
		ITopicControlAddContextCallback< TContext >	callback
	)

Sends a request to the server to add a topic.

The topic will be initialized with the given value during creation and therefore the value must be compatible with the TopicType. Otherwise, an TopicAddFailReason.INITIALISE_ERROR will be returned.

If the given value is null this call has the same effect as calling AddTopic(string,ITopicDetails,ITopicControlAddCallback). A value can only be supplied for a topic type that maintains state.

Template Parameters

TContext The context type.

Parameters

topicPath	The topic path to which the topic will be bound.
details	The details of the topic to be created.
value	The initial value.
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 , details , or callback is `null`.
System.ArgumentException	The details are invalid (eg. custom implementation or stateless topic).

Task<AddTopicResult> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopicAsync	(	string	topicPath,
		TopicType	topicType
	)

Requests creation of a topic.

If the task completes successfully, the Task result will indicate whether a new topic was created, or whether a topic with an identical topic specification is already bound to the given topicPath.

This is a convenience method that is equivalent to:

topicControl.AddTopicAsync(

"myTopic", topicControl.NewSpecification( topicType ) );

Since 6.0

Parameters

topicPath	The topic path to which the topic will be bound.
topicType	The type of topic to be created.

Returns: The task representing the current operation.

Exceptions

ArgumentNullException	The topicPath or topicType is `null`.
SessionClosedException	The session is closed. Thrown by the returned task.
ExistingTopicException	The topic bound to topicPath already exists with different specifications. Thrown by the returned task.
InvalidTopicPathException	The topicPath is invalid. Thrown by the returned task.
SessionSecurityException	The calling session does not have TopicPermission.MODIFY_TOPIC permissions for the given topicPath. Thrown by the returned task.
ReferencedTopicDoesNotExistException	The specification references an unknown topic. Thrown by the returned task.
InvalidTopicSpecificationException	The specification is invalid. Thrown by the returned task.
ClusterRepartitionException	The cluster was repartitioning. Thrown by the returned task.
AddTopicException	The topic could not be created. Thrown by the returned task.
InvalidOperationException	The server response was invalid. Thrown by the returned task.

See Also: AddTopicAsync(string, TopicType, CancellationToken)

Task<AddTopicResult> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopicAsync	(	string	topicPath,
		TopicType	topicType,
		CancellationToken	cancellationToken
	)

Requests creation of a topic.

If the task completes successfully, the Task result will indicate whether a new topic was created, or whether a topic with an identical topic specification is already bound to the given topicPath.

This is a convenience method that is equivalent to:

topicControl.AddTopicAsync(

"myTopic", topicControl.NewSpecification( topicType ), src.Token );

Since 6.0

Parameters

topicPath	The topic path to which the topic will be bound.
topicType	The type of topic to be created.
cancellationToken	The cancellation token used to cancel the current operation.

Returns: The task representing the current operation.

Exceptions

ArgumentNullException	The topicPath or topicType is `null`.
SessionClosedException	The session is closed. Thrown by the returned task.
ExistingTopicException	The topic bound to topicPath already exists with different specifications. Thrown by the returned task.
InvalidTopicPathException	The topicPath is invalid. Thrown by the returned task.
SessionSecurityException	The calling session does not have TopicPermission.MODIFY_TOPIC permissions for the given topicPath. Thrown by the returned task.
ReferencedTopicDoesNotExistException	The specification references an unknown topic. Thrown by the returned task.
InvalidTopicSpecificationException	The specification is invalid. Thrown by the returned task.
ClusterRepartitionException	The cluster was repartitioning. Thrown by the returned task.
AddTopicException	The topic could not be created. Thrown by the returned task.
InvalidOperationException	The server response was invalid. Thrown by the returned task.

Adding a topic

try {
    var src = new CancellationTokenSource();
    await session.TopicControl.AddTopicAsync( "myTopic", TopicType.JSON, src.Token );
} catch ( SessionClosedException ex ) {
    Console.WriteLine( $"Creation failed. Reason: {ex}." );
} catch ( SessionSecurityException ex ) {
    Console.WriteLine( $"Creation failed. Reason: {ex}." );
} // Catch other relevant exceptions if necessary

Task<AddTopicResult> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopicAsync	(	string	topicPath,
		ITopicSpecification	specification
	)

Requests creation of a topic.

If the task completes successfully, the Task result will indicate whether a new topic was created, or whether a topic with an identical topic specification is already bound to the given topicPath.

Since 6.0

Parameters

topicPath	The topic path to which the topic will be bound.
specification	The topic specification that defines the topic to be created. Can be created using NewSpecification.

Returns: The task representing the current operation.

Exceptions

ArgumentNullException	The topicPath or specification is `null`.
SessionClosedException	The session is closed. Thrown by the returned task.
ExistingTopicException	The topic bound to topicPath already exists with different specifications. Thrown by the returned task.
InvalidTopicPathException	The topicPath is invalid. Thrown by the returned task.
SessionSecurityException	The calling session does not have TopicPermission.MODIFY_TOPIC permissions for the given topicPath. Thrown by the returned task.
ReferencedTopicDoesNotExistException	The specification references an unknown topic. Thrown by the returned task.
InvalidTopicSpecificationException	The specification is invalid. Thrown by the returned task.
ClusterRepartitionException	The cluster was repartitioning. Thrown by the returned task.
AddTopicException	The topic could not be created. Thrown by the returned task.
InvalidOperationException	The server response was invalid. Thrown by the returned task.

See Also: AddTopicAsync(string, ITopicSpecification, CancellationToken)

Task<AddTopicResult> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopicAsync	(	string	topicPath,
		ITopicSpecification	specification,
		CancellationToken	cancellationToken
	)

Requests creation of a topic.

If the task completes successfully, the Task result will indicate whether a new topic was created, or whether a topic with an identical topic specification is already bound to the given topicPath.

Since 6.0

Parameters

topicPath	The topic path to which the topic will be bound.
specification	The topic specification that defines the topic to be created. Can be created using NewSpecification.
cancellationToken	The cancellation token used to cancel the current operation.

Returns: The task representing the current operation.

Exceptions

ArgumentNullException	The topicPath or specification is `null`.
SessionClosedException	The session is closed. Thrown by the returned task.
ExistingTopicException	The topic bound to topicPath already exists with different specifications. Thrown by the returned task.
InvalidTopicPathException	The topicPath is invalid. Thrown by the returned task.
SessionSecurityException	The calling session does not have TopicPermission.MODIFY_TOPIC permissions for the given topicPath. Thrown by the returned task.
ReferencedTopicDoesNotExistException	The specification references an unknown topic. Thrown by the returned task.
InvalidTopicSpecificationException	The specification is invalid. Thrown by the returned task.
ClusterRepartitionException	The cluster was repartitioning. Thrown by the returned task.
AddTopicException	The topic could not be created. Thrown by the returned task.
InvalidOperationException	The server response was invalid. Thrown by the returned task.

Adding a topic

try {
    var src = new CancellationTokenSource();
    await session.TopicControl.AddTopicAsync(
        "myTopic", session.TopicControl.NewSpecification( TopicType.JSON ), src.Token );
} catch ( SessionClosedException ex ) {
    Console.WriteLine( $"Creation failed. Reason: {ex}." );
} catch ( SessionSecurityException ex ) {
    Console.WriteLine( $"Creation failed. Reason: {ex}." );
} // Catch other relevant exceptions if necessary

void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopicEventListener	(	string	topicPath,
		ITopicControlTopicEventListener	listener
	)

Registers a ITopicControlTopicEventListener to receive topic events for a branch of the topic tree.

Events are emitted when a topic is subscribed to by one or more sessions after previously having no subscribers and when a topic is no longer subscribed to by any session. These events are averaged over a small window of time to prevent rapid dispatch of events that ultimately return a topic to its previous state.

Parameters

topicPath	The branch of the topic tree.
listener	The event listener for the given topic tree branch.

Exceptions

System.ArgumentNullException The topicPath , or listener is null.

Task<IRegistration> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopicEventListenerAsync	(	string	topicPath,
		ITopicEventStream	stream
	)

Registers a ITopicEventStream to receive topic events for a branch of the topic tree.

Events are emitted when a topic is subscribed to by one or more sessions after previously having no subscribers and when a topic is no longer subscribed to by any session. These events are averaged over a small window of time to prevent rapid dispatch of events that ultimately return a topic to its previous state.

If registration was successful, the Task will complete successfully with a IRegistration which can be used to unregister the stream.

Since 6.0

Parameters

topicPath	The branch of the topic tree.
stream	The stream for the specified branch (unless overridden by a stream registered against a more specific branch)

Returns: The task representing the current operation.

Exceptions

ArgumentNullException	The topicPath or stream is `null`.
SessionClosedException	The session is closed. Thrown by the returned task.
SessionSecurityException	The calling session does not have GlobalPermission.REGISTER_HANDLER permissions. Thrown by the returned task.
HandlerConflictException	The session has already registered a event stream for the topicPath . Thrown by the returned task.

See Also: AddTopicEventListenerAsync(string, ITopicEventStream, CancellationToken)

Task<IRegistration> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopicEventListenerAsync	(	string	topicPath,
		ITopicEventStream	stream,
		CancellationToken	cancellationToken
	)

Registers a ITopicEventStream to receive topic events for a branch of the topic tree.

Events are emitted when a topic is subscribed to by one or more sessions after previously having no subscribers and when a topic is no longer subscribed to by any session. These events are averaged over a small window of time to prevent rapid dispatch of events that ultimately return a topic to its previous state.

If registration was successful, the Task will complete successfully with a IRegistration which can be used to unregister the stream.

Since 6.0

Parameters

topicPath	The branch of the topic tree.
stream	The stream for the specified branch (unless overridden by a stream registered against a more specific branch)
cancellationToken	The cancellation token used to cancel the current operation.

Returns: The task representing the current operation.

Exceptions

ArgumentNullException	The topicPath or stream is `null`.
SessionClosedException	The session is closed. Thrown by the returned task.
SessionSecurityException	The calling session does not have GlobalPermission.REGISTER_HANDLER permissions. Thrown by the returned task.
HandlerConflictException	The session has already registered a event stream for the topicPath . Thrown by the returned task.

ITopicDetails PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopicFromValue< TValue >	(	string	topicPath,
		TValue	value,
		ITopicControlAddCallback	callback
	)

Sends a request to the server to add a topic where the type and initial value for the topic are derived from a provided value object.

The topic type, metadata (if applicable) and initial value are derived from a supplied value.

Since 5.3

Template Parameters

TValue The value type.

Parameters

topicPath	The topic path to which the topic will be bound.
value	The initial value.
callback	The callback object to receive status notifications for this operation.

Returns: The details used to add the topic.

Exceptions

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

ITopicDetails PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.AddTopicFromValue< TValue, TContext >	(	string	topicPath,
		TValue	value,
		TContext	context,
		ITopicControlAddContextCallback< TContext >	callback
	)

Sends a request to the server to add a topic where the type and initial value for the topic are derived from a provided value object.

The topic type, metadata (if applicable) and initial value are derived from a supplied value.

Since 5.3

Template Parameters

TValue	The value type.
TContext	The context type.

Parameters

topicPath	The topic path to which the topic will be bound.
value	The initial value.
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.

Returns: The details used to add the topic.

Exceptions

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

TBuilder PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.CreateDetailsBuilder< TBuilder > ( )

Creates a new topic details builder to create ITopicDetails of a type corresponding to the given builder type.

Template Parameters

TBuilder The builder type.

Returns: The new builder that can be used to build topic details of the type indicated by the given builder type.

Type Constraints

TBuilder	:	class
TBuilder	:	ITopicDetailsBuilder<ITopicDetails>

ITopicDetails PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.NewDetails ( TopicType topicType )

Returns new topic details of the given type set with all default settings.

This provides a simpler mechanism than creating a builder where all of the builder's default values are suitable and there are no mandatory properties.

If using this mechanism, it is important to understand what the default details for the topic type would be. The documentation of the relevant ITopicDetailsBuilder subtype should be consulted.

Parameters

topicType The topic type.

Returns: The new topic details of the type indicated by the given topic type.

Exceptions

System.ArgumentNullException The topicType is null.

ITopicSpecification PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.NewSpecification ( TopicType topicType )

Creates a new ITopicSpecification for a given topic type.

Since 5.8

Parameters

topicType The topic type.

Returns: The new immutable specification with no properties set. New specifications with properties set may be produced using the ITopicSpecification.WithProperty(string,string) or ITopicSpecification.WithProperties methods of the provided specification.

Exceptions

System.ArgumentNullException The topicType is null.

void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.Remove	(	string	topicSelector,
		ITopicControlRemovalCallback	callback
	)

Sends a request to remove one or more topics.

All topics that match the provided topicSelector that the caller has permission to remove will be removed.

The selector's descendant pattern qualifier (a trailing

/

or

//

), can be used to remove descendant topics. If a single

/

qualifier is specified, all descendants of the matched topic paths will be removed. If

//

is specified, the matched paths and all descendants of the matched paths (complete branches) will be removed.

Since 5.9.

Parameters

topicSelector	The topic selector expression specifying the topics to remove.
callback	The callback object to receive status notifications for this operation.

Exceptions

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

void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.Remove< TContext >	(	string	topicSelector,
		TContext	context,
		ITopicControlRemovalContextCallback< TContext >	callback
	)

Sends a request to remove one or more topics.

All topics that match the given topicSelector that the caller has permission to remove will be removed. The selector's descendant pattern qualifier (a trailing "/" or "//"), can be used to remove descendant topics. If a single "/" qualifier is specified, all descendants of the matched topic paths will be removed. If "//" is specified, the matched paths and all descendants of the matched paths (complete branches) will be removed.

Since 5.9.

Template Parameters

TContext The context type.

Parameters

topicSelector	The topic selector expression specifying the topics to remove.
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 topicSelector expression, or callback is `null`.
System.ArgumentException	The topicSelector expression is not a valid selector expression.

Task<object> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.RemoveTopicsAsync ( string topicSelector )

Sends a request to remove one or more 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.

This is equivalent to calling

RemoveTopicsAsync

with a selector parsed using TopicSelectors.Parse.

All topics that match the provided topicSelector that the caller has permission to remove will be removed.

The selector's descendant pattern qualifier (a trailing

/

or

//

) can be used to remove descendant topics. If a single

/

qualifier is specified, all descendants of the matched topic paths will be removed. If

//

is specified, the matched paths and all descendants of the matched paths (complete branches) will be removed.

Since 6.0

Parameters

topicSelector The selector expression specifying the topics to remove.

Returns: The task representing the current operation.

Exceptions

ArgumentNullException	The topicSelector expression is `null`.
SessionClosedException	The session is closed. Thrown by the returned task.

See Also: RemoveTopicsAsync(string, CancellationToken)

Task<object> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.RemoveTopicsAsync	(	string	topicSelector,
		CancellationToken	cancellationToken
	)

Sends a request to remove one or more 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.

This is equivalent to calling

RemoveTopicsAsync

with a selector parsed using TopicSelectors.Parse.

All topics that match the provided topicSelector that the caller has permission to remove will be removed.

The selector's descendant pattern qualifier (a trailing

/

or

//

) can be used to remove descendant topics. If a single

/

qualifier is specified, all descendants of the matched topic paths will be removed. If

//

is specified, the matched paths and all descendants of the matched paths (complete branches) will be removed.

Since 6.0

Parameters

topicSelector	The selector expression specifying the topics to remove.
cancellationToken	The cancellation token used to cancel the current operation.

Returns: The task representing the current operation.

Exceptions

ArgumentNullException	The topicSelector expression is `null`.
SessionClosedException	The session is closed. Thrown by the returned task.

Removing a topic

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

Task<object> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.RemoveTopicsAsync ( ITopicSelector topicSelector )

Sends a request to remove one or more topics.

All topics that match the provided topicSelector that the caller has permission to remove will be removed.

The selector's descendant pattern qualifier (a trailing

/

or

//

) can be used to remove descendant topics. If a single

/

qualifier is specified, all descendants of the matched topic paths will be removed. If

//

is specified, the matched paths and all descendants of the matched paths (complete branches) will be removed.

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

topicSelector The selector specifying the topics to remove.

Returns: The task representing the current operation.

Exceptions

ArgumentNullException	The topicSelector expression is `null`.
SessionClosedException	The session is closed. Thrown by the returned task.

See Also: RemoveTopicsAsync(ITopicSelector, CancellationToken)

Task<object> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.RemoveTopicsAsync	(	ITopicSelector	topicSelector,
		CancellationToken	cancellationToken
	)

Sends a request to remove one or more topics.

All topics that match the provided topicSelector that the caller has permission to remove will be removed.

The selector's descendant pattern qualifier (a trailing

/

or

//

) can be used to remove descendant topics. If a single

/

qualifier is specified, all descendants of the matched topic paths will be removed. If

//

is specified, the matched paths and all descendants of the matched paths (complete branches) will be removed.

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

topicSelector	The selector specifying the topics to remove.
cancellationToken	The cancellation token used to cancel the current operation.

Returns: The task representing the current operation.

Exceptions

ArgumentNullException	The topicSelector expression is `null`.
SessionClosedException	The session is closed. Thrown by the returned task.

Removing a topic

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

void PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.RemoveTopicsWithSession	(	string	topicPath,
		Callbacks.ITopicTreeHandler	registrationHandler
	)

Register a deferred action to remove all topics that the caller has permission to remove from a branch of the topic tree.

The server will remove the topics if this session is closed. If several sessions request removal of the same branch, the topics will not be removed until the last session is closed.

For example, suppose two sessions both call RemoveTopicsWithSession( "a/b", registrationHandler). When both sessions are closed, either explicitly using ISession.Close() or by the server, the topic "a/b" and all of its descendants will be removed. This method is typically used by a session that has added topics to remove the topics if it is ever disconnected from the server or otherwise fails.

The server will reject a the method call if the given topicPath conflicts with existing registrations. Different sessions can call this method for the same topic path, but not for topic paths above or below existing registrations on the same branch of the topic tree.

The following callbacks will be delivered to the given registrationHandler :

If registration succeeds, Callbacks.ITopicTreeHandler.OnRegistered(string, IRegistration) will be called as notification that the deferred action is active. A IRegistration is provided that allows the deferred action to be de-registered.
If deregistration is successful, Callbacks.ITopicTreeHandler.OnClose(string) will be called as notification that the deferred action is no longer active. No further calls will be made to the given registrationHandler .
If the registration or deregistration fails, Callbacks.ITopicTreeHandler.OnError(string,ErrorReason) will be called and no further calls will be made to the given registrationHandler . In general, this is non-recoverable; the deferred action may or may not be active and the application can do little more than report the condition. In the specific case that OnError is called with ErrorReason.TOPIC_TREE_REGISTRATION_CONFLICT, registration has failed due to a pre-existing registration on the same branch of the topic tree as the given topicPath .

The last session to close must have TopicPermission.MODIFY_TOPIC permission for all topics to be removed beneath topicPath . If this is not the case at the time the session closes, only those topics that the last session had permission to remove will be removed.

Since 5.1

Parameters

topicPath	The path of the topic to be removed.
registrationHandler	The callback object to receive status notifications for this operation.

Exceptions

System.ArgumentNullException The topicPath , or registrationHandler is null.

Task<IRegistration> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.RemoveTopicsWithSessionAsync ( string topicPath )

Register a deferred action to remove all topics that the caller has permission to remove from a branch of the topic tree.

The server will remove the topics if this session is closed. If several sessions request removal of the same branch, the topics will not be removed until the last session is closed.

For example, suppose two sessions both call

RemoveTopicsWithSessionAsync( "a/b" )

. When both sessions are closed, either explicitly using ISession.Close() or by the server, the topic "a/b" and all of its descendants will be removed. This method is typically used by a session that has added topics to remove the topics if it is ever disconnected from the server or otherwise fails.

The server will reject the method call if the given topicPath conflicts with existing registrations. Different sessions can call this method for the same topic path, but not for topic paths above or below existing registrations on the same branch of the topic tree.

The last session to close must have TopicPermission.MODIFY_TOPIC permission for all topics to be removed beneath topicPath . If this is not the case at the time the session closes, only those topics that the last session had permission to remove will be removed.

If registration was successful, the Task will complete successfully with a IRegistration value as notification that the deferred removal action is active.

Since 6.0

Parameters

topicPath The topic and its descendants to be removed if the action is executed.

Returns: The task representing the current operation.

Exceptions

ArgumentNullException	The topicPath is `null`.
SessionClosedException	The session is closed. Thrown by the returned task.
SessionSecurityException	The calling session does not have TopicPermission.MODIFY_TOPIC permissions for the path prefix of the given selector. Thrown by the returned task.
HandlerConflictException	A session has already registered an active RemoveTopicsWithSessionAsync registration for a different topic path belonging to the same branch of the topic tree. Thrown by the returned task.

See Also: RemoveTopicsWithSessionAsync(string, CancellationToken)

Task<IRegistration> PushTechnology.ClientInterface.Client.Features.Control.Topics.ITopicControl.RemoveTopicsWithSessionAsync	(	string	topicPath,
		CancellationToken	cancellationToken
	)

Register a deferred action to remove all topics that the caller has permission to remove from a branch of the topic tree.

The server will remove the topics if this session is closed. If several sessions request removal of the same branch, the topics will not be removed until the last session is closed.

For example, suppose two sessions both call

RemoveTopicsWithSessionAsync( "a/b" )

. When both sessions are closed, either explicitly using ISession.Close() or by the server, the topic "a/b" and all of its descendants will be removed. This method is typically used by a session that has added topics to remove the topics if it is ever disconnected from the server or otherwise fails.

The server will reject the method call if the given topicPath conflicts with existing registrations. Different sessions can call this method for the same topic path, but not for topic paths above or below existing registrations on the same branch of the topic tree.

The last session to close must have TopicPermission.MODIFY_TOPIC permission for all topics to be removed beneath topicPath . If this is not the case at the time the session closes, only those topics that the last session had permission to remove will be removed.

If registration was successful, the Task will complete successfully with a IRegistration value as notification that the deferred removal action is active.

Since 6.0

Parameters

topicPath	The topic and its descendants to be removed if the action is executed.
cancellationToken	The cancellation token used to cancel the current operation.

Returns: The task representing the current operation.

Exceptions

ArgumentNullException	The topicPath is `null`.
SessionClosedException	The session is closed. Thrown by the returned task.
SessionSecurityException	The calling session does not have TopicPermission.MODIFY_TOPIC permissions for the path prefix of the given selector. Thrown by the returned task.
HandlerConflictException	A session has already registered an active RemoveTopicsWithSessionAsync registration for a different topic path belonging to the same branch of the topic tree. Thrown by the returned task.

Removing a topic associated with the session

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

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

Client.Public/Features/Control/Topics/ITopicControl.cs

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation