Interface ISecurity

This feature provides a client session with the ability to change its associated principal as well as to query permissions assigned to it.

Inherited Members

IFeature.Session

Namespace: PushTechnology.ClientInterface.Client.Features

Assembly: Diffusion.Client.dll

Syntax

public interface ISecurity : IFeature

Remarks

Access control

There are no permissions requirements associated with this feature. The client provides credentials that authenticate the new principal.

Accessing the feature

This feature may be obtained from an ISession as follows:

var security = session.Security;

Added in version 5.0.

Methods

ChangePrincipal(String, ICredentials, IChangePrincipalCallback)

Changes the security principal associated with the calling session.

Declaration

void ChangePrincipal(string principal, ICredentials credentials, IChangePrincipalCallback callback)

Parameters

Type	Name	Description
String	principal	The new principal for the calling session.
ICredentials	credentials	The credentials authenticating the new principal.
IChangePrincipalCallback	callback	The callback to receive status notifications for this operation.

Remarks

Caution

Deprecated since 6.7. Methods that use callbacks are deprecated and will be removed in a future release. Use a Task instead.

If authentication fails, the session's current principal will not be changed.

ChangePrincipal<TContext>(String, ICredentials, TContext, IChangePrincipalContextCallback<TContext>)

Changes the security principal associated with the calling session.

Declaration

void ChangePrincipal<TContext>(string principal, ICredentials credentials, TContext context, IChangePrincipalContextCallback<TContext> callback)

Parameters

Type	Name	Description
String	principal	The new principal for the calling session.
ICredentials	credentials	The credentials authenticating the new principal.
TContext	context	The context of this operation.
IChangePrincipalContextCallback<TContext>	callback	The callback to receive status notifications for this operation.

Type Parameters

Name	Description
TContext	The context type.

Remarks

Caution

Deprecated since 6.7. Methods that use contextual callbacks are deprecated and will be removed in a future release. Use a Task instead.

If authentication fails, the session's current principal will not be changed.

ChangePrincipalAsync(String, ICredentials)

Changes the security principal associated with the session.

Declaration

Task<bool> ChangePrincipalAsync(string principal, ICredentials credentials)

Parameters

Type	Name	Description
String	principal	The new principal for the calling session.
ICredentials	credentials	The credentials authenticating the new principal.

Returns

Type	Description
Task<Boolean>	The Task representing the current operation.

Remarks

If the operation completes successfully, the Task result will be a System.Boolean value. true indicates that the authentication succeeded and the session principal has been changed to the given principal. false indicates that the authentication failed because the given principal was unknown or the given credentials were invalid, the session's principal has not changed.

This method is the same as calling ChangePrincipalAsync(String, ICredentials, CancellationToken) with System.Threading.CancellationToken.None.

Exceptions

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

ChangePrincipalAsync(String, ICredentials, CancellationToken)

Changes the security principal associated with the session.

Declaration

Task<bool> ChangePrincipalAsync(string principal, ICredentials credentials, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	principal	The new principal for the calling session.
ICredentials	credentials	The credentials authenticating the new principal.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<Boolean>	The Task representing the current operation.

Remarks

If the operation completes successfully, the Task result will be a System.Boolean value. true indicates that the authentication succeeded and the session principal has been changed to the given principal. false indicates that the authentication failed because the given principal was unknown or the given credentials were invalid, the session's principal has not changed.

Exceptions

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

GetGlobalPermissionsAsync()

Queries the global permissions assigned to the calling session.

Declaration

Task<IReadOnlyCollection<GlobalPermission>> GetGlobalPermissionsAsync()

Returns

Type	Description
Task<IReadOnlyCollection<GlobalPermission>>	The Task representing the current operation.

Remarks

If the operation completes succesfully, the Task result will be a collection containing the session's global permissions.

GetGlobalPermissionsAsync(CancellationToken)

Queries the global permissions assigned to the calling session.

Declaration

Task<IReadOnlyCollection<GlobalPermission>> GetGlobalPermissionsAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<IReadOnlyCollection<GlobalPermission>>	The Task representing the current operation.

Remarks

If the operation completes succesfully, the Task result will be a collection containing the session's global permissions.

GetPermissionsForPathAsync(String)

Queries the path permissions assigned to the calling session on a given path.

Declaration

Task<IReadOnlyCollection<PathPermission>> GetPermissionsForPathAsync(string path)

Parameters

Type	Name	Description
String	path	The topic path to query for permissions.

Returns

Type	Description
Task<IReadOnlyCollection<PathPermission>>	The Task representing the current operation.

Remarks

If the operation completes succesfully, the Task result will be a collection containing the session's permissions for path.

Added in 6.5.

GetPermissionsForPathAsync(String, CancellationToken)

Queries the path permissions assigned to the calling session on a given path.

Declaration

Task<IReadOnlyCollection<PathPermission>> GetPermissionsForPathAsync(string path, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	path	The topic path to query for permissions.
CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
Task<IReadOnlyCollection<PathPermission>>	The Task representing the current operation.

Remarks

If the operation completes succesfully, the Task result will be a collection containing the session's permissions for path.

Added in 6.5.