Class MultiplexingStream

Namespace

Nerdbank.Streams

Assembly

Nerdbank.Streams.dll

Encodes multiple channels over a single transport.

public class MultiplexingStream : IDisposableObservable, IDisposable, IAsyncDisposable

Inheritance

object

MultiplexingStream

Implements

IDisposableObservable

IDisposable

IAsyncDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Properties

Completion

Gets a task that completes when this instance is disposed, and may have captured a fault that led to its self-disposal.

public Task Completion { get; }

Property Value

Task

DefaultChannelReceivingWindowSize

Gets the default window size used for new channels that do not specify a value for ChannelReceivingWindowSize.

public long DefaultChannelReceivingWindowSize { get; }

Property Value

long

Remarks

This value can be set at the time of creation of the MultiplexingStream via DefaultChannelReceivingWindowSize.

TraceSource

Gets the logger used by this instance.

public TraceSource TraceSource { get; }

Property Value

TraceSource

Never null.

Methods

AcceptChannel(int, ChannelOptions?)

Accepts a channel with a specific ID.

public MultiplexingStream.Channel AcceptChannel(int id, MultiplexingStream.ChannelOptions? options = null)

Parameters

id int

The Id of the channel to accept.

options MultiplexingStream.ChannelOptions

A set of options that describe local treatment of this channel.

Returns

MultiplexingStream.Channel

The accepted MultiplexingStream.Channel.

Remarks

This method can be used to accept anonymous channels created with CreateChannel(ChannelOptions?). Unlike AcceptChannelAsync(string, ChannelOptions?, CancellationToken) which will await for a channel offer if a matching one has not been made yet, this method only accepts an offer for a channel that has already been made.

Exceptions

InvalidOperationException

Thrown if the channel is already accepted or is no longer offered by the remote party.

InvalidOperationException

Thrown when no channel with the specified id exists.

AcceptChannel(ulong, ChannelOptions?)

Accepts a channel with a specific ID.

public MultiplexingStream.Channel AcceptChannel(ulong id, MultiplexingStream.ChannelOptions? options = null)

Parameters

id ulong

The Id of the channel to accept.

options MultiplexingStream.ChannelOptions

A set of options that describe local treatment of this channel.

Returns

MultiplexingStream.Channel

The accepted MultiplexingStream.Channel.

Remarks

This method can be used to accept anonymous channels created with CreateChannel(ChannelOptions?). Unlike AcceptChannelAsync(string, ChannelOptions?, CancellationToken) which will await for a channel offer if a matching one has not been made yet, this method only accepts an offer for a channel that has already been made.

Exceptions

InvalidOperationException

Thrown if the channel is already accepted or is no longer offered by the remote party.

InvalidOperationException

Thrown when no channel with the specified id exists.

AcceptChannelAsync(string, ChannelOptions?, CancellationToken)

Accepts a channel that the remote end has attempted or may attempt to create.

public Task<MultiplexingStream.Channel> AcceptChannelAsync(string name, MultiplexingStream.ChannelOptions? options = null, CancellationToken cancellationToken = default)

Parameters

name string

The name of the channel to accept. An empty string will match an offer made via OfferChannelAsync(string, ChannelOptions?, CancellationToken) with an empty channel name. It will also match an anonymous channel offer made with CreateChannel(ChannelOptions?).

options MultiplexingStream.ChannelOptions

A set of options that describe local treatment of this channel.

cancellationToken CancellationToken

A token to indicate lost interest in accepting the channel.

Returns

Task<MultiplexingStream.Channel>

The MultiplexingStream.Channel, after its offer has been received from the remote party and accepted.

Remarks

If multiple offers exist with the specified name, the first one received will be accepted.

Exceptions

InvalidOperationException

Thrown if the channel is already accepted or is no longer offered by the remote party.

OperationCanceledException

Thrown if cancellationToken is canceled before a request to create the channel has been received.

AcceptChannelAsync(string, CancellationToken)

Accepts a channel that the remote end has attempted or may attempt to create.

public Task<MultiplexingStream.Channel> AcceptChannelAsync(string name, CancellationToken cancellationToken)

Parameters

name string

The name of the channel to accept. An empty string will match an offer made via OfferChannelAsync(string, ChannelOptions?, CancellationToken) with an empty channel name. It will also match an anonymous channel offer made with CreateChannel(ChannelOptions?).

cancellationToken CancellationToken

A token to indicate lost interest in accepting the channel.

Returns

Task<MultiplexingStream.Channel>

The MultiplexingStream.Channel, after its offer has been received from the remote party and accepted.

Remarks

If multiple offers exist with the specified name, the first one received will be accepted.

Exceptions

InvalidOperationException

Thrown if the channel is already accepted or is no longer offered by the remote party.

OperationCanceledException

Thrown if cancellationToken is canceled before a request to create the channel has been received.

Create(Stream, Options?)

Initializes a new instance of the MultiplexingStream class with ProtocolMajorVersion set to 3.

public static MultiplexingStream Create(Stream stream, MultiplexingStream.Options? options = null)

Parameters

stream Stream

The stream to multiplex multiple channels over. Use Splice(Stream, Stream) if you have distinct input/output streams.

options MultiplexingStream.Options

Options to define behavior for the multiplexing stream.

Returns

MultiplexingStream

The multiplexing stream.

CreateAsync(Stream, Options?, CancellationToken)

Initializes a new instance of the MultiplexingStream class.

public static Task<MultiplexingStream> CreateAsync(Stream stream, MultiplexingStream.Options? options, CancellationToken cancellationToken = default)

Parameters

stream Stream

The stream to multiplex multiple channels over. Use Splice(Stream, Stream) if you have distinct input/output streams.

options MultiplexingStream.Options

Options to define behavior for the multiplexing stream. If unspecified, the default options will include ProtocolMajorVersion set to 1.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<MultiplexingStream>

The multiplexing stream, once the handshake is complete.

Exceptions

EndOfStreamException

Thrown if the remote end disconnects before the handshake is complete.

CreateAsync(Stream, CancellationToken)

Initializes a new instance of the MultiplexingStream class.

public static Task<MultiplexingStream> CreateAsync(Stream stream, CancellationToken cancellationToken = default)

Parameters

stream Stream

The stream to multiplex multiple channels over. Use Splice(Stream, Stream) if you have distinct input/output streams.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<MultiplexingStream>

The multiplexing stream, once the handshake is complete.

Exceptions

EndOfStreamException

Thrown if the remote end disconnects before the handshake is complete.

CreateChannel(ChannelOptions?)

Creates an anonymous channel that may be accepted by AcceptChannel(int, ChannelOptions?). Its existance must be communicated by other means (typically another, existing channel) to encourage acceptance.

public MultiplexingStream.Channel CreateChannel(MultiplexingStream.ChannelOptions? options = null)

Parameters

options MultiplexingStream.ChannelOptions

A set of options that describe local treatment of this channel.

Returns

MultiplexingStream.Channel

The anonymous channel.

Remarks

Note that while the channel is created immediately, any local write to that channel will be buffered locally until the remote party accepts the channel.

Dispose()

Immediately closes the underlying transport stream and releases all resources associated with this object and any open channels.

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

DisposeAsync()

Disposes this multiplexing stream.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that indicates when disposal is complete.

OfferChannelAsync(string, ChannelOptions?, CancellationToken)

Offers a new, named channel to the remote party so they may accept it with AcceptChannelAsync(string, ChannelOptions?, CancellationToken).

public Task<MultiplexingStream.Channel> OfferChannelAsync(string name, MultiplexingStream.ChannelOptions? options = null, CancellationToken cancellationToken = default)

Parameters

name string

A name for the channel, which must be accepted on the remote end to complete creation. It need not be unique, and may be empty but must not be null. Any characters are allowed, and max length is determined by the maximum frame payload (based on UTF-8 encoding).

options MultiplexingStream.ChannelOptions

A set of options that describe local treatment of this channel.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<MultiplexingStream.Channel>

A task that completes with the MultiplexingStream.Channel if the offer is accepted on the remote end or faults with MultiplexingProtocolException if the remote end rejects the channel.

Exceptions

OperationCanceledException

Thrown if cancellationToken is canceled before the channel is accepted by the remote end.

OfferChannelAsync(string, CancellationToken)

Offers a new, named channel to the remote party so they may accept it with AcceptChannelAsync(string, ChannelOptions?, CancellationToken).

public Task<MultiplexingStream.Channel> OfferChannelAsync(string name, CancellationToken cancellationToken)

Parameters

name string

A name for the channel, which must be accepted on the remote end to complete creation. It need not be unique, and may be empty but must not be null. Any characters are allowed, and max length is determined by the maximum frame payload (based on UTF-8 encoding).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<MultiplexingStream.Channel>

A task that completes with the MultiplexingStream.Channel if the offer is accepted on the remote end or faults with MultiplexingProtocolException if the remote end rejects the channel.

Exceptions

OperationCanceledException

Thrown if cancellationToken is canceled before the channel is accepted by the remote end.

OnChannelOffered(ChannelOfferEventArgs)

Raises the ChannelOffered event.

protected virtual void OnChannelOffered(MultiplexingStream.ChannelOfferEventArgs args)

Parameters

args MultiplexingStream.ChannelOfferEventArgs

The arguments to pass to the event handlers.

RejectChannel(int)

Rejects an offer for the channel with a specified ID.

public void RejectChannel(int id)

Parameters

id int

The ID of the channel whose offer should be rejected.

Exceptions

InvalidOperationException

Thrown if the channel was already accepted.

RejectChannel(ulong)

Rejects an offer for the channel with a specified ID.

public void RejectChannel(ulong id)

Parameters

id ulong

The ID of the channel whose offer should be rejected.

Exceptions

InvalidOperationException

Thrown if the channel was already accepted.

StartListening()

Starts reading from the stream.

public void StartListening()

Remarks

This should only be done once, on an instance created with StartSuspended set to true and only after any required event handlers have been added so as to avoid a race where incoming messages lead to raising events before handlers have been added.

Events

ChannelOffered

Occurs when the remote party offers to establish a channel.

public event EventHandler<MultiplexingStream.ChannelOfferEventArgs>? ChannelOffered

Event Type

EventHandler<MultiplexingStream.ChannelOfferEventArgs>

Remarks

When adding a handler to this event, consider whether the stream has already started listening and you may have already missed some incoming events. If you want to receive all events from the start, be sure to create the MultiplexingStream with StartSuspended set to true, then add handler(s) to this event before calling StartListening().