Interface IReferencePreservingSerializer<TEncoder, TDecoder>

Namespace

ShapeShift

Assembly

ShapeShift.dll

Implemented by a format's serializer when the format can represent a back-reference to an object it has already written.

public interface IReferencePreservingSerializer<TEncoder, TDecoder> where TEncoder : IEncoder, allows ref struct where TDecoder : IDecoder, allows ref struct

Type Parameters

TEncoder

The format's encoder type.

TDecoder

The format's decoder type.

Remarks

There is no format-neutral way to say "this value is a reference to the object written earlier" without colliding with data that happens to look the same, so each format that supports ShapeShift.SerializerConfiguration<TEncoder, TDecoder>.PreserveReferences defines its own unambiguous token -- a reserved extension type, for example -- and implements this interface to read and write it.

A serializer that does not implement this interface rejects any attempt to enable reference preservation, rather than silently writing a graph as a tree.

Properties

PreserveReferences

Gets a setting that determines how references to objects are preserved during serialization and deserialization.

ReferencePreservationMode PreserveReferences { get; }

Property Value

ReferencePreservationMode

The default value is Off because it requires no msgpack extensions, is compatible with all msgpack readers, adds no security considerations and is the most performant.

Remarks

Preserving references impacts the serialized result and can hurt interoperability if the other party is not using the same feature.

Methods

TryReadObjectReference(ref TDecoder, out int, SerializationContext<TEncoder, TDecoder>)

Reads a back-reference if the next token is one.

bool TryReadObjectReference(ref TDecoder reader, out int referenceId, SerializationContext<TEncoder, TDecoder> context)

Parameters

reader TDecoder

The decoder to read from.

referenceId int

Receives the identifier when the next token is a back-reference.

context SerializationContext<TEncoder, TDecoder>

The serialization context.

Returns

bool

true when a back-reference was consumed; false when the next token is ordinary data, which must be left unconsumed.

WriteObjectReference(ref TEncoder, int, SerializationContext<TEncoder, TDecoder>)

Writes a back-reference to an object that has already been written.

void WriteObjectReference(ref TEncoder writer, int referenceId, SerializationContext<TEncoder, TDecoder> context)

Parameters

writer TEncoder

The encoder to write to.

referenceId int

The non-negative identifier of the previously written object.

context SerializationContext<TEncoder, TDecoder>

The serialization context.