Class MessageHandlerBase

Namespace

StreamJsonRpc

Assembly

StreamJsonRpc.dll

An abstract base class for for sending and receiving messages.

public abstract class MessageHandlerBase : IJsonRpcMessageHandler, IDisposableObservable, IDisposable, IAsyncDisposable

Inheritance

object

MessageHandlerBase

Implements

IJsonRpcMessageHandler

IDisposableObservable

IDisposable

IAsyncDisposable

Derived

PipeMessageHandler

StreamMessageHandler

WebSocketMessageHandler

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This class and its derivatives are safe to call from any thread. Calls to WriteAsync(JsonRpcMessage, CancellationToken) are protected by a semaphore to guarantee message integrity and may be made from any thread. The caller must take care to call ReadAsync(CancellationToken) sequentially.

Constructors

MessageHandlerBase(IJsonRpcMessageFormatter)

Initializes a new instance of the MessageHandlerBase class.

public MessageHandlerBase(IJsonRpcMessageFormatter formatter)

Parameters

formatter IJsonRpcMessageFormatter

The formatter used to serialize messages.

Properties

CanRead

Gets a value indicating whether this message handler can receive messages.

public abstract bool CanRead { get; }

Property Value

bool

CanWrite

Gets a value indicating whether this message handler can send messages.

public abstract bool CanWrite { get; }

Property Value

bool

DisposalToken

Gets a token that is canceled when this instance is disposed.

protected CancellationToken DisposalToken { get; }

Property Value

CancellationToken

Formatter

Gets the formatter used for message serialization.

public IJsonRpcMessageFormatter Formatter { get; }

Property Value

IJsonRpcMessageFormatter

Methods

Dispose()

Disposes this instance, and cancels any pending read or write operations.

[Obsolete("Call IAsyncDisposable.DisposeAsync instead.")]
public void Dispose()

Dispose(bool)

Disposes resources allocated by this instance that are common to both reading and writing.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

true when being disposed; false when being finalized.

Remarks

This method is called by DisposeAsync() after both DisposeReader() and DisposeWriter() have completed.

Overrides of this method *should* call the base method as well.

DisposeAsync()

Disposes this instance, and cancels any pending read or write operations.

public virtual Task DisposeAsync()

Returns

Task

DisposeReader()

Disposes resources allocated by this instance that are used for reading (not writing).

protected virtual void DisposeReader()

Remarks

This method is called by MessageHandlerBase after the last read operation has completed.

DisposeWriter()

Disposes resources allocated by this instance that are used for writing (not reading).

protected virtual void DisposeWriter()

Remarks

This method is called by MessageHandlerBase after the last write operation has completed. Overrides of this method should call the base method as well.

FlushAsync(CancellationToken)

Ensures that all messages transmitted up to this point are en route to their destination, rather than sitting in some local buffer.

protected abstract ValueTask FlushAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A Task that completes when the write buffer has been transmitted, or at least that the operation is in progress, if final transmission cannot be tracked.

ReadAsync(CancellationToken)

Reads a distinct and complete message from the transport, waiting for one if necessary.

public ValueTask<JsonRpcMessage?> ReadAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A token to cancel the read request.

Returns

ValueTask<JsonRpcMessage>

The received message, or null if the underlying transport ends before beginning another message.

Remarks

Implementations may assume this method is never called before any async result from a prior call to this method has completed.

Exceptions

InvalidOperationException

Thrown when CanRead returns false.

EndOfStreamException

Thrown if the transport ends while reading a message.

OperationCanceledException

Thrown if cancellationToken is canceled before a new message is received.

ReadCoreAsync(CancellationToken)

Reads a distinct and complete message, waiting for one if necessary.

protected abstract ValueTask<JsonRpcMessage?> ReadCoreAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

A token to cancel the read request.

Returns

ValueTask<JsonRpcMessage>

A task whose result is the received message. A null string indicates the stream has ended. An empty string should never be returned.

WriteAsync(JsonRpcMessage, CancellationToken)

Writes a message to the transport and flushes.

public ValueTask WriteAsync(JsonRpcMessage content, CancellationToken cancellationToken)

Parameters

content JsonRpcMessage

The message to write.

cancellationToken CancellationToken

A token to cancel the write request.

Returns

ValueTask

A task that represents the asynchronous operation.

Remarks

Implementations should expect this method to be invoked concurrently and use a queue to preserve message order as they are transmitted one at a time.

Exceptions

InvalidOperationException

Thrown when CanWrite returns false.

OperationCanceledException

Thrown if cancellationToken is canceled before message transmission begins.

ObjectDisposedException

Thrown if this instance is disposed before or during transmission.

WriteCoreAsync(JsonRpcMessage, CancellationToken)

Writes a message.

protected abstract ValueTask WriteCoreAsync(JsonRpcMessage content, CancellationToken cancellationToken)

Parameters

content JsonRpcMessage

The message to write.

cancellationToken CancellationToken

A token to cancel the transmission.

Returns

ValueTask

A task that represents the asynchronous write operation.