Struct MessagePackStreamingReader

Namespace

Nerdbank.MessagePack

Assembly

Nerdbank.MessagePack.dll

A msgpack decoder that returns error codes rather than throws exceptions when the buffer is incomplete or the token type does not match expectations.

public ref struct MessagePackStreamingReader

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Examples

The following snippet demonstrates a common pattern for properly reading with this type.

int count;
while (streamingReader.TryReadArrayHeader(out count).NeedsMoreBytes())
{
    streamingReader = new(await streamingReader.FetchMoreBytesAsync());
}

Remarks

All decoding methods on this struct return MessagePackPrimitives.DecodeResult. Callers must take care to observe this value and take appropriate action. A common calling pattern is to call the decoding method within a while loop's expression and use the NeedsMoreBytes(DecodeResult) extension method on the result. The content of the loop should be a call to FetchMoreBytesAsync(uint) and to reconstruct the reader using MessagePackStreamingReader(scoped in BufferRefresh).

Constructors

MessagePackStreamingReader(scoped in BufferRefresh)

Initializes a new instance of the MessagePackStreamingReader struct that resumes after an await operation.

public MessagePackStreamingReader(scoped in MessagePackStreamingReader.BufferRefresh refresh)

Parameters

refresh MessagePackStreamingReader.BufferRefresh

The data to reinitialize this ref struct.

MessagePackStreamingReader(scoped in ReadOnlySequence<byte>)

Initializes a new instance of the MessagePackStreamingReader struct that decodes from a complete buffer.

public MessagePackStreamingReader(scoped in ReadOnlySequence<byte> sequence)

Parameters

sequence ReadOnlySequence<byte>

The buffer to decode msgpack from. This buffer should be complete.

MessagePackStreamingReader(scoped in ReadOnlySequence<byte>, GetMoreBytesAsync?, object?)

Initializes a new instance of the MessagePackStreamingReader struct that decodes from a buffer that may be initially incomplete.

public MessagePackStreamingReader(scoped in ReadOnlySequence<byte> sequence, MessagePackStreamingReader.GetMoreBytesAsync? additionalBytesSource, object? getMoreBytesState)

Parameters

sequence ReadOnlySequence<byte>

The buffer we have so far.

additionalBytesSource MessagePackStreamingReader.GetMoreBytesAsync

A means to obtain more msgpack bytes when necessary.

getMoreBytesState object

A value to provide to the getMoreBytesState delegate. This facilitates reuse of a particular delegate across deserialization operations.

Properties

CancellationToken

Gets a token that may cancel deserialization.

public CancellationToken CancellationToken { readonly get; init; }

Property Value

CancellationToken

Position

Gets the reader's position within the current buffer.

public SequencePosition Position { get; }

Property Value

SequencePosition

Methods

FetchMoreBytesAsync(uint)

Adds more bytes to the buffer being decoded, if they are available.

public ValueTask<MessagePackStreamingReader.BufferRefresh> FetchMoreBytesAsync(uint minimumLength = 1)

Parameters

minimumLength uint

The minimum number of bytes to fetch before returning.

Returns

ValueTask<MessagePackStreamingReader.BufferRefresh>

The value to pass to MessagePackStreamingReader(scoped in BufferRefresh).

Remarks

This is a destructive operation to this MessagePackStreamingReader value. It must not be used after calling this method. Instead, the result can use the result of this method to recreate a new MessagePackStreamingReader value.

Exceptions

EndOfStreamException

Thrown if no more bytes are available.

GetExchangeInfo()

Gets the information to return from an async method that has been using this reader so that the caller knows how to resume reading.

public readonly MessagePackStreamingReader.BufferRefresh GetExchangeInfo()

Returns

MessagePackStreamingReader.BufferRefresh

The value to pass to MessagePackStreamingReader(scoped in BufferRefresh).

TryPeekNextCode(out byte)

Peeks at the next msgpack byte without advancing the reader.

public MessagePackPrimitives.DecodeResult TryPeekNextCode(out byte code)

Parameters

code byte

When successful, receives the next msgpack byte.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TryPeekNextMessagePackType(out MessagePackType)

Peeks at the next msgpack token type without advancing the reader.

public MessagePackPrimitives.DecodeResult TryPeekNextMessagePackType(out MessagePackType type)

Parameters

type MessagePackType

When successful, receives the next msgpack token type.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TryRead(out Extension)

Reads an extension from the msgpack stream.

public MessagePackPrimitives.DecodeResult TryRead(out Extension extension)

Parameters

extension Extension

Receives the extension if the read was successful.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TryRead(ExtensionHeader, out DateTime)

Reads a DateTime value from the msgpack stream, assuming the given ExtensionHeader.

public MessagePackPrimitives.DecodeResult TryRead(ExtensionHeader extensionHeader, out DateTime value)

Parameters

extensionHeader ExtensionHeader

The extension header that was previously read.

value DateTime

The decoded value if the read was successful.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TryRead(out ExtensionHeader)

Reads an extension header from the msgpack stream.

public MessagePackPrimitives.DecodeResult TryRead(out ExtensionHeader extensionHeader)

Parameters

extensionHeader ExtensionHeader

Receives the extension header if the read was successful.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TryRead(out bool)

Reads a bool value from the msgpack stream.

public MessagePackPrimitives.DecodeResult TryRead(out bool value)

Parameters

value bool

The decoded value if the read was successful.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TryRead(out byte)

Reads an byte value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.

public MessagePackPrimitives.DecodeResult TryRead(out byte value)

Parameters

value byte

Receives the decoded value.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

Exceptions

OverflowException

Thrown when the value exceeds what can be stored in the returned type.

TryRead(out DateTime)

Reads a DateTime value from the msgpack stream.

public MessagePackPrimitives.DecodeResult TryRead(out DateTime value)

Parameters

value DateTime

The decoded value if the read was successful.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TryRead(out double)

Reads a double value from the msgpack stream.

public MessagePackPrimitives.DecodeResult TryRead(out double value)

Parameters

value double

The decoded value if the read was successful.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TryRead(out short)

Reads an short value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.

public MessagePackPrimitives.DecodeResult TryRead(out short value)

Parameters

value short

Receives the decoded value.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

Exceptions

OverflowException

Thrown when the value exceeds what can be stored in the returned type.

TryRead(out int)

Reads an int value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.

public MessagePackPrimitives.DecodeResult TryRead(out int value)

Parameters

value int

Receives the decoded value.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

Exceptions

OverflowException

Thrown when the value exceeds what can be stored in the returned type.

TryRead(out long)

Reads an long value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.

public MessagePackPrimitives.DecodeResult TryRead(out long value)

Parameters

value long

Receives the decoded value.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

Exceptions

OverflowException

Thrown when the value exceeds what can be stored in the returned type.

TryRead(out sbyte)

Reads an sbyte value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.

public MessagePackPrimitives.DecodeResult TryRead(out sbyte value)

Parameters

value sbyte

Receives the decoded value.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

Exceptions

OverflowException

Thrown when the value exceeds what can be stored in the returned type.

TryRead(out float)

Reads a float value from the msgpack stream.

public MessagePackPrimitives.DecodeResult TryRead(out float value)

Parameters

value float

The decoded value if the read was successful.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TryRead(out string?)

Reads a string or null value from the msgpack stream.

public MessagePackPrimitives.DecodeResult TryRead(out string? value)

Parameters

value string

The decoded value if the read was successful.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TryRead(out ushort)

Reads an ushort value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.

public MessagePackPrimitives.DecodeResult TryRead(out ushort value)

Parameters

value ushort

Receives the decoded value.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

Exceptions

OverflowException

Thrown when the value exceeds what can be stored in the returned type.

TryRead(out uint)

Reads an uint value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.

public MessagePackPrimitives.DecodeResult TryRead(out uint value)

Parameters

value uint

Receives the decoded value.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

Exceptions

OverflowException

Thrown when the value exceeds what can be stored in the returned type.

TryRead(out ulong)

Reads an ulong value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.

public MessagePackPrimitives.DecodeResult TryRead(out ulong value)

Parameters

value ulong

Receives the decoded value.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

Exceptions

OverflowException

Thrown when the value exceeds what can be stored in the returned type.

TryReadArrayHeader(out int)

Reads an array header from the msgpack stream.

public MessagePackPrimitives.DecodeResult TryReadArrayHeader(out int count)

Parameters

count int

The number of elements in the array, if the read was successful.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TryReadBinHeader(out uint)

Tries to read the header of binary data.

public MessagePackPrimitives.DecodeResult TryReadBinHeader(out uint length)

Parameters

length uint

Receives the length of the binary data, when successful.

Returns

MessagePackPrimitives.DecodeResult

The result classification of the read operation.

Remarks

Reads a binary data header from Bin8, Bin16, or Bin32.

Note that in the original msgpack spec, there were no binary data headers, so binary data was introduced using string headers. This should be read using TryReadStringHeader(ReadOnlySpan<byte>, out uint, out int).

TryReadBinary(out ReadOnlySequence<byte>)

Reads a binary sequence with an appropriate msgpack header from the msgpack stream.

public MessagePackPrimitives.DecodeResult TryReadBinary(out ReadOnlySequence<byte> value)

Parameters

value ReadOnlySequence<byte>

The byte sequence if the read was successful.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TryReadMapHeader(out int)

Reads a map header from the msgpack stream.

public MessagePackPrimitives.DecodeResult TryReadMapHeader(out int count)

Parameters

count int

The number of elements in the map, if the read was successful.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TryReadNil()

Reads the next token if it is Nil.

public MessagePackPrimitives.DecodeResult TryReadNil()

Returns

MessagePackPrimitives.DecodeResult

Success if the token was nil and was read, TokenMismatch if the token was not nil, or other error codes if the buffer is incomplete.

TryReadNil(out bool)

Reads the next token if it is Nil.

public MessagePackPrimitives.DecodeResult TryReadNil(out bool isNil)

Parameters

isNil bool

A value indicating whether the next token was nil.

Returns

MessagePackPrimitives.DecodeResult

Success if the next token can be decoded whether or not it was nil, or other error codes if the buffer is incomplete.

TryReadRaw(long, out ReadOnlySequence<byte>)

Reads a given number of bytes from the msgpack stream without decoding them.

public MessagePackPrimitives.DecodeResult TryReadRaw(long length, out ReadOnlySequence<byte> rawMsgPack)

Parameters

length long

The number of bytes to read.

rawMsgPack ReadOnlySequence<byte>

The bytes if the read was successful.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TryReadStringHeader(out uint)

Tries to read the header of a string.

public MessagePackPrimitives.DecodeResult TryReadStringHeader(out uint length)

Parameters

length uint

Receives the length of the next string, when successful.

Returns

MessagePackPrimitives.DecodeResult

The result classification of the read operation.

Remarks

Reads a string header from Str8, Str16, Str32, or any value between MinFixStr and MaxFixStr.

Note that in the original msgpack spec, there were no binary data headers, so binary data was introduced using string headers.

TryReadStringSequence(out ReadOnlySequence<byte>)

Reads a byte sequence backing a UTF-8 encoded string with an appropriate msgpack header from the msgpack stream.

public MessagePackPrimitives.DecodeResult TryReadStringSequence(out ReadOnlySequence<byte> value)

Parameters

value ReadOnlySequence<byte>

The byte sequence if the read was successful.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TryReadStringSpan(out bool, out ReadOnlySpan<byte>)

Reads a span backing a UTF-8 encoded string with an appropriate msgpack header from the msgpack stream, if the string is contiguous in memory.

public MessagePackPrimitives.DecodeResult TryReadStringSpan(out bool contiguous, out ReadOnlySpan<byte> value)

Parameters

contiguous bool

Receives a value indicating whether the string was present and contiguous in memory.

value ReadOnlySpan<byte>

The span of bytes if the read was successful.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

TrySkip(ref SerializationContext)

Advances the reader past the next msgpack structure.

public MessagePackPrimitives.DecodeResult TrySkip(ref SerializationContext context)

Parameters

context SerializationContext

The context of the deserialization operation.

Returns

MessagePackPrimitives.DecodeResult

The success or error code.

Remarks

The reader position is changed when the return value is Success. The reader position and the context may also be changed when the return value is InsufficientBuffer, such that after fetching more bytes, a follow-up call to this method can resume skipping.