Class StreamUtils

Namespace

VpnHood.Net.Toolkit.Streams

Assembly

VpnHood.Net.Toolkit.dll

Provides the framing of JSON messages on a stream: a 4-byte little-endian length, then that many bytes of UTF-8 JSON. The readers limit the payload; the writers do not.

public static class StreamUtils

Inheritance

object

StreamUtils

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Fields

MaxMessageLength

The readers' default largest payload, in bytes, after the 4-byte length: 512 KB; a payload of exactly it is accepted.

public const int MaxMessageLength = 524288

Field Value

int

Methods

ObjectToJsonBuffer(object)

Frames an object as a JSON message, by its runtime type.

public static Memory<byte> ObjectToJsonBuffer(object obj)

Parameters

obj object

The object.

Returns

Memory<byte>

The frame: the length, then the JSON.

ObjectToJsonBuffer(object, JsonTypeInfo)

Frames an object as a JSON message, with its type's metadata.

public static Memory<byte> ObjectToJsonBuffer(object obj, JsonTypeInfo jsonTypeInfo)

Parameters

obj object

The object.

jsonTypeInfo JsonTypeInfo

The type's metadata.

Returns

Memory<byte>

The frame: the length, then the JSON.

ObjectToJsonBuffer<T>(T, JsonTypeInfo<T>)

Frames an object as a JSON message, with its metadata.

public static Memory<byte> ObjectToJsonBuffer<T>(T obj, JsonTypeInfo<T> jsonTypeInfo)

Parameters

obj T

The object.

jsonTypeInfo JsonTypeInfo<T>

The type's metadata.

Returns

Memory<byte>

The frame: the length, then the JSON.

Type Parameters

T

The object's type.

ReadMessageAsync(Stream, int, CancellationToken)

Reads a framed message's text; it rejects a frame whose next four bytes are HTTP.

public static Task<string> ReadMessageAsync(Stream stream, int maxLength, CancellationToken cancellationToken)

Parameters

stream Stream

The stream.

maxLength int

The largest message accepted, in bytes.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<string>

A task whose result is the text.

Exceptions

FormatException

The length is negative, or over maxLength.

Exception

The length is zero.

EndOfStreamException

The stream ends early.

UnauthorizedAccessException

The stream's next four bytes are HTTP.

OperationCanceledException

cancellationToken was canceled.

DecoderFallbackException

The message's bytes are no UTF-8.

ReadMessageAsync(Stream, CancellationToken)

Reads a framed message's text, of at most MaxMessageLength.

public static Task<string> ReadMessageAsync(Stream stream, CancellationToken cancellationToken)

Parameters

stream Stream

The stream.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<string>

A task whose result is the text.

Exceptions

FormatException

The length is negative, or over the largest.

Exception

The length is zero.

EndOfStreamException

The stream ends early.

UnauthorizedAccessException

The stream's next four bytes are HTTP.

OperationCanceledException

cancellationToken was canceled.

DecoderFallbackException

The message's bytes are no UTF-8.

ReadObjectAsync<T>(Stream, int, CancellationToken)

Reads a framed JSON message as an object.

public static Task<T> ReadObjectAsync<T>(Stream stream, int maxLength, CancellationToken cancellationToken)

Parameters

stream Stream

The stream.

maxLength int

The largest message accepted, in bytes.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<T>

A task whose result is the object.

Type Parameters

T

The object's type.

Exceptions

FormatException

The length is negative, or over maxLength.

Exception

The length is zero, or the deserialization returns null.

EndOfStreamException

The stream ends early.

JsonException

The message is no JSON of the type, as when its bytes are no UTF-8.

UnauthorizedAccessException

The stream's next four bytes are HTTP.

OperationCanceledException

cancellationToken was canceled.

ReadObjectAsync<T>(Stream, JsonTypeInfo<T>, int, CancellationToken)

Reads a framed JSON message as an object with its metadata.

public static Task<T> ReadObjectAsync<T>(Stream stream, JsonTypeInfo<T> jsonTypeInfo, int maxLength, CancellationToken cancellationToken)

Parameters

stream Stream

The stream.

jsonTypeInfo JsonTypeInfo<T>

The type's metadata.

maxLength int

The largest message accepted, in bytes.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<T>

A task whose result is the object.

Type Parameters

T

The object's type.

Exceptions

FormatException

The length is negative, or over maxLength.

Exception

The length is zero, or the deserialization returns null.

EndOfStreamException

The stream ends early.

JsonException

The message is no JSON of the type, as when its bytes are no UTF-8.

UnauthorizedAccessException

The stream's next four bytes are HTTP.

OperationCanceledException

cancellationToken was canceled.

ReadObjectAsync<T>(Stream, JsonTypeInfo<T>, CancellationToken)

Reads a framed JSON message as an object with its metadata, of at most MaxMessageLength.

public static Task<T> ReadObjectAsync<T>(Stream stream, JsonTypeInfo<T> jsonTypeInfo, CancellationToken cancellationToken)

Parameters

stream Stream

The stream.

jsonTypeInfo JsonTypeInfo<T>

The type's metadata.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<T>

A task whose result is the object.

Type Parameters

T

The object's type.

Exceptions

FormatException

The length is negative, or over the largest.

Exception

The length is zero, or the deserialization returns null.

EndOfStreamException

The stream ends early.

JsonException

The message is no JSON of the type, as when its bytes are no UTF-8.

UnauthorizedAccessException

The stream's next four bytes are HTTP.

OperationCanceledException

cancellationToken was canceled.

ReadObjectAsync<T>(Stream, CancellationToken)

Reads a framed JSON message as an object, of at most MaxMessageLength.

public static Task<T> ReadObjectAsync<T>(Stream stream, CancellationToken cancellationToken)

Parameters

stream Stream

The stream.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task<T>

A task whose result is the object.

Type Parameters

T

The object's type.

Exceptions

FormatException

The length is negative, or over the largest.

Exception

The length is zero, or the deserialization returns null.

EndOfStreamException

The stream ends early.

JsonException

The message is no JSON of the type, as when its bytes are no UTF-8.

UnauthorizedAccessException

The stream's next four bytes are HTTP.

OperationCanceledException

cancellationToken was canceled.

ReadObject<T>(Stream, int)

Reads a framed JSON message as an object, synchronously.

public static T ReadObject<T>(Stream stream, int maxLength = 524288)

Parameters

stream Stream

The stream.

maxLength int

The largest message accepted, in bytes.

Returns

T

The object.

Type Parameters

T

The object's type.

Exceptions

FormatException

The length is negative, or over maxLength.

Exception

The length is zero, or the deserialization returns null.

EndOfStreamException

The stream ends early.

JsonException

The message is no JSON of the type, as when its bytes are no UTF-8.

WriteObject(Stream, object)

Writes an object as a framed JSON message, synchronously.

public static void WriteObject(Stream stream, object obj)

Parameters

stream Stream

The stream.

obj object

The object.

WriteObjectAsync(Stream, object, JsonTypeInfo, CancellationToken)

Writes an object as a framed JSON message, with its type's metadata.

public static ValueTask WriteObjectAsync(Stream stream, object obj, JsonTypeInfo jsonTypeInfo, CancellationToken cancellationToken)

Parameters

stream Stream

The stream.

obj object

The object.

jsonTypeInfo JsonTypeInfo

The type's metadata.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

ValueTask

A task that represents the asynchronous operation.

Exceptions

OperationCanceledException

cancellationToken was canceled.

WriteObjectAsync(Stream, object, CancellationToken)

Writes an object as a framed JSON message, by its runtime type.

public static ValueTask WriteObjectAsync(Stream stream, object obj, CancellationToken cancellationToken)

Parameters

stream Stream

The stream.

obj object

The object.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

ValueTask

A task that represents the asynchronous operation.

Exceptions

OperationCanceledException

cancellationToken was canceled.

WriteObjectAsync<T>(Stream, T, JsonTypeInfo<T>, CancellationToken)

Writes an object as a framed JSON message, with its metadata.

public static ValueTask WriteObjectAsync<T>(Stream stream, T obj, JsonTypeInfo<T> jsonTypeInfo, CancellationToken cancellationToken)

Parameters

stream Stream

The stream.

obj T

The object.

jsonTypeInfo JsonTypeInfo<T>

The type's metadata.

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

ValueTask

A task that represents the asynchronous operation.

Type Parameters

T

The object's type.

Exceptions

OperationCanceledException

cancellationToken was canceled.