Table of Contents

Struct MessagePackReader

Namespace
Nerdbank.MessagePack
Assembly
Nerdbank.MessagePack.dll

A primitive types reader for the MessagePack format.

public ref struct MessagePackReader
Inherited Members

Remarks

The MessagePack spec..

Constructors

MessagePackReader(scoped in ReadOnlySequence<byte>)

Initializes a new instance of the MessagePackReader struct.

public MessagePackReader(scoped in ReadOnlySequence<byte> msgpack)

Parameters

msgpack ReadOnlySequence<byte>

The sequence to read from.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

MessagePackReader(ReadOnlyMemory<byte>)

Initializes a new instance of the MessagePackReader struct.

public MessagePackReader(ReadOnlyMemory<byte> msgpack)

Parameters

msgpack ReadOnlyMemory<byte>

The sequence to read from.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

Properties

CancellationToken

Gets or sets the cancellation token for this deserialization operation.

public CancellationToken CancellationToken { readonly get; set; }

Property Value

CancellationToken

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

Consumed

Gets the number of bytes consumed by the reader.

public long Consumed { get; }

Property Value

long

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

End

Gets a value indicating whether the reader is at the end of the sequence.

public bool End { get; }

Property Value

bool

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

IsNil

Gets a value indicating whether the reader position is pointing at a nil value.

public bool IsNil { get; }

Property Value

bool

Exceptions

EndOfStreamException

Thrown if the end of the sequence provided to the constructor is reached before the expected end of the data.

NextCode

Gets the type of the next MessagePack block.

public byte NextCode { get; }

Property Value

byte

Remarks

See MessagePackCode for valid message pack codes and ranges.

Exceptions

EndOfStreamException

Thrown if the end of the sequence provided to the constructor is reached before the expected end of the data.

NextMessagePackType

Gets the next message pack type to be read.

public MessagePackType NextMessagePackType { get; }

Property Value

MessagePackType

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

Position

Gets the current position of the reader within Sequence.

public SequencePosition Position { get; }

Property Value

SequencePosition

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

Sequence

Gets the ReadOnlySequence<T> originally supplied to the constructor.

public ReadOnlySequence<byte> Sequence { get; }

Property Value

ReadOnlySequence<byte>

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

Methods

Clone(scoped in ReadOnlySequence<byte>)

Initializes a new instance of the MessagePackReader struct, with the same settings as this one, but with its own buffer to read from.

public MessagePackReader Clone(scoped in ReadOnlySequence<byte> readOnlySequence)

Parameters

readOnlySequence ReadOnlySequence<byte>

The sequence to read from.

Returns

MessagePackReader

The new reader.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

CreatePeekReader()

Creates a new MessagePackReader at this reader's current position. The two readers may then be used independently without impacting each other.

public MessagePackReader CreatePeekReader()

Returns

MessagePackReader

A new MessagePackReader.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

ReadArrayHeader()

Read an array header from Array16, Array32, or some built-in code between MinFixArray and MaxFixArray.

public int ReadArrayHeader()

Returns

int

The number of elements in the array.

Exceptions

EndOfStreamException

Thrown if the header cannot be read in the bytes left in the Sequence or if it is clear that there are insufficient bytes remaining after the header to include all the elements the header claims to be there.

MessagePackSerializationException

Thrown if a code other than an array header is encountered.

ReadBoolean()

Reads a boolean value from either a False or True.

public bool ReadBoolean()

Returns

bool

The value.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

ReadByte()

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 byte ReadByte()

Returns

byte

The value.

Exceptions

OverflowException

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

ReadBytes()

Reads a span of bytes, whose length is determined by a header of one of these types: Bin8, Bin16, Bin32, or to support OldSpec compatibility: Str16, Str32, or something between MinFixStr and MaxFixStr.

public ReadOnlySequence<byte>? ReadBytes()

Returns

ReadOnlySequence<byte>?

A sequence of bytes, or null if the read token is Nil. The data is a slice from the original sequence passed to this reader's constructor.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

ReadChar()

Reads a char from any of: UInt8, UInt16, or anything between MinFixInt and MaxFixInt.

public char ReadChar()

Returns

char

A character.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

ReadDateTime()

Reads a DateTime from a value encoded with FixExt4, FixExt8, or Ext8. Expects extension type code DateTime.

public DateTime ReadDateTime()

Returns

DateTime

The value.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

ReadDateTime(ExtensionHeader)

Reads a DateTime from a value encoded with FixExt4, FixExt8, Ext8. Expects extension type code DateTime.

public DateTime ReadDateTime(ExtensionHeader header)

Parameters

header ExtensionHeader

The extension header that was already read.

Returns

DateTime

The value.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

ReadDouble()

Reads an double value from any value encoded with: Float64, Float32, Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64, or some value between MinNegativeFixInt and MaxNegativeFixInt, or some value between MinFixInt and MaxFixInt.

public double ReadDouble()

Returns

double

The value.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

ReadExtension()

Reads an extension format header and data, based on one of these codes: FixExt1, FixExt2, FixExt4, FixExt8, FixExt16, Ext8, Ext16, or Ext32.

public Extension ReadExtension()

Returns

Extension

The extension format. The data is a slice from the original sequence passed to this reader's constructor.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

ReadExtensionHeader()

Reads an extension format header, based on one of these codes: FixExt1, FixExt2, FixExt4, FixExt8, FixExt16, Ext8, Ext16, or Ext32.

public ExtensionHeader ReadExtensionHeader()

Returns

ExtensionHeader

The extension header.

Exceptions

EndOfStreamException

Thrown if the header cannot be read in the bytes left in the Sequence or if it is clear that there are insufficient bytes remaining after the header to include all the bytes the header claims to be there.

MessagePackSerializationException

Thrown if a code other than an extension format header is encountered.

ReadInt16()

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 short ReadInt16()

Returns

short

The value.

Exceptions

OverflowException

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

ReadInt32()

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 int ReadInt32()

Returns

int

The value.

Exceptions

OverflowException

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

ReadInt64()

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 long ReadInt64()

Returns

long

The value.

Exceptions

OverflowException

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

ReadMapHeader()

Read a map header from Map16, Map32, or some built-in code between MinFixMap and MaxFixMap.

public int ReadMapHeader()

Returns

int

The number of key=value pairs in the map.

Exceptions

EndOfStreamException

Thrown if the header cannot be read in the bytes left in the Sequence or if it is clear that there are insufficient bytes remaining after the header to include all the elements the header claims to be there.

MessagePackSerializationException

Thrown if a code other than an map header is encountered.

ReadNil()

Reads a Nil value.

public void ReadNil()

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

ReadRaw(SerializationContext)

Reads the next MessagePack structure.

public ReadOnlySequence<byte> ReadRaw(SerializationContext context)

Parameters

context SerializationContext

The serialization context. Used for the stack guard.

Returns

ReadOnlySequence<byte>

The raw MessagePack sequence, taken as a slice from the Sequence. The caller should copy any data that must out-live its underlying buffers.

Remarks

The entire structure is read, including content of maps or arrays, or any other type with payloads.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

ReadRaw(long)

Reads a sequence of bytes without any decoding.

public ReadOnlySequence<byte> ReadRaw(long length)

Parameters

length long

The number of bytes to read.

Returns

ReadOnlySequence<byte>

The raw MessagePack sequence, taken as a slice from the Sequence. The caller should copy any data that must out-live its underlying buffers.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

ReadSByte()

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 sbyte ReadSByte()

Returns

sbyte

The value.

Exceptions

OverflowException

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

ReadSingle()

Reads an float value from any value encoded with: Float32, Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64, or some value between MinNegativeFixInt and MaxNegativeFixInt, or some value between MinFixInt and MaxFixInt.

public float ReadSingle()

Returns

float

The value.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

ReadString()

Reads a string, whose length is determined by a header of one of these types: Str8, Str16, Str32, or a code between MinFixStr and MaxFixStr.

public string? ReadString()

Returns

string

A string, or null if the current msgpack token is Nil.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

ReadStringSequence()

Reads a string of bytes, whose length is determined by a header of one of these types: Str8, Str16, Str32, or a code between MinFixStr and MaxFixStr.

public ReadOnlySequence<byte>? ReadStringSequence()

Returns

ReadOnlySequence<byte>?

The sequence of bytes, or null if the read token is Nil. The data is a slice from the original sequence passed to this reader's constructor.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

ReadUInt16()

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 ushort ReadUInt16()

Returns

ushort

The value.

Exceptions

OverflowException

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

ReadUInt32()

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 uint ReadUInt32()

Returns

uint

The value.

Exceptions

OverflowException

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

ReadUInt64()

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 ulong ReadUInt64()

Returns

ulong

The value.

Exceptions

OverflowException

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

Skip(SerializationContext)

Advances the reader to the next MessagePack structure to be read.

public void Skip(SerializationContext context)

Parameters

context SerializationContext

Serialization context. Used for the stack guard.

Remarks

The entire structure is skipped, including content of maps or arrays, or any other type with payloads. To get the raw MessagePack sequence that was skipped, use ReadRaw(SerializationContext) instead.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

TryReadArrayHeader(out int)

Reads an array header from Array16, Array32, or some built-in code between MinFixArray and MaxFixArray if there is sufficient buffer to read it.

public bool TryReadArrayHeader(out int count)

Parameters

count int

Receives the number of elements in the array if the entire array header could be read.

Returns

bool

true if there was sufficient buffer and an array header was found; false if the buffer incompletely describes an array header.

Exceptions

MessagePackSerializationException

Thrown if a code other than an array header is encountered.

TryReadExtensionHeader(out ExtensionHeader)

Reads an extension format header, based on one of these codes: FixExt1, FixExt2, FixExt4, FixExt8, FixExt16, Ext8, Ext16, or Ext32 if there is sufficient buffer to read it.

public bool TryReadExtensionHeader(out ExtensionHeader extensionHeader)

Parameters

extensionHeader ExtensionHeader

Receives the extension header if the remaining bytes in the Sequence fully describe the header.

Returns

bool

The number of key=value pairs in the map.

Remarks

When this method returns false the position of the reader is left in an undefined position. The caller is expected to recreate the reader (presumably with a longer sequence to read from) before continuing.

Exceptions

MessagePackSerializationException

Thrown if a code other than an extension format header is encountered.

TryReadMapHeader(out int)

Reads a map header from Map16, Map32, or some built-in code between MinFixMap and MaxFixMap if there is sufficient buffer to read it.

public bool TryReadMapHeader(out int count)

Parameters

count int

Receives the number of key=value pairs in the map if the entire map header can be read.

Returns

bool

true if there was sufficient buffer and a map header was found; false if the buffer incompletely describes an map header.

Exceptions

MessagePackSerializationException

Thrown if a code other than an map header is encountered.

TryReadNil()

Reads nil if it is the next token.

public bool TryReadNil()

Returns

bool

true if the next token was nil; false otherwise.

Exceptions

EndOfStreamException

Thrown if the end of the sequence provided to the constructor is reached before the expected end of the data.

TryReadStringSpan(out ReadOnlySpan<byte>)

Reads a string of bytes, whose length is determined by a header of one of these types: Str8, Str16, Str32, or a code between MinFixStr and MaxFixStr.

public bool TryReadStringSpan(out ReadOnlySpan<byte> span)

Parameters

span ReadOnlySpan<byte>

Receives the span to the string.

Returns

bool

true if the string is contiguous in memory such that it could be set as a single span. false if the read token is Nil or the string is not in a contiguous span.

Remarks

Callers should generally be prepared for a false result and failover to calling ReadStringSequence() which can represent a null result and handle strings that are not contiguous in memory.

Exceptions

MessagePackSerializationException

Thrown when reading methods fail due to invalid data.

EndOfStreamException

Thrown by reading methods when there are not enough bytes to read the required value.

Edit this page