Purpose

It is a library to read and write native structs from and to byte arrays by .NET programs in a way that is natural for .NET.

It's main purpose is to be used by the NISAM library.

Java port

The library is a port of a similar Java library, so an occasional Java'ism may be found.

Getting started

To use the library you need to:

• create POCO classes that contains all the fields in the native structs
• put annotations on the class and the fields that tell the library how the data are mapped to the native structs
• write the code that uses the library and the new POCO classes

Note:

• the POCO classes should have a no args constructor
• the library does not care whether you use private fields and public properties or public fields (the first is .NET best practice)
• all fields except static fields must have attributes defining reading/writing

Examples:

POCO class

    [Struct]
    public class Data
    {
        [StructField(N=0,Type=FieldType.INT4)]
        private int iv;
        [StructField(N=1,Type=FieldType.FP8)]
        private double xv;
        [StructField(N=2,Type=FieldType.FIXSTR,Length=8,Encoding="ISO-8859-1")]
        private String sv;
        public int Iv
        {
            get { return iv; }
            set { iv = value; }
        }
        public double Xv
        {
            get { return xv; }
            set { xv = value; }
        }
        public string Sv
        {
            get { return sv; }
            set { sv = value; }
        }
    }

The class got a [Struct] attribute. Each field in the class got a [StructField] attribute with an element N that determines the order of the fields and an element type that describes the datatype in the native struct plus some optional elements that are needed for some field types.

Code fragments

// read
StructReader sr = new StructReader(somebytearray);
Data obj = sr.Read<Data>(typeof(Data));
// write
Data obj = new Data();
...
StructWriter sw = new StructWriter();
sw.Write(obj);
byte[] ba = sw.GetBytes();

Arrays

To specify a field as an array put an @Array annotation on the field and make the .NET type an array.

Sub structs

To specify a field as a sub struct just specify Type=FieldType.STRUCT in the [StructField] attribute.

Polymorphism

The Record library supports polymorphism in records.

You must use the [Selector] attribute on the last field in the super class.

    [Struct]
    public class SuperData
    {
        [StructField(N=0,Type=FieldType.INT4)]
        private int id;
        [StructField(N=1,Type=FieldType.INT4)]
        [Selector]
        [SubType(Value=1,Type=typeof(DataX))]
        [SubType(Value=2,Type=typeof(DataY))]
        private int typ;
        public int Id
        {
            get { return id; }
            set { id = value; }
        }
        public int Typ
        {
            get { return typ; }
            set { typ = value; }
        }
    }

Usage is as simple as:

Data obj = sr.Read<Data>(typeof(Data));

This will actually read DataX or DataY instances depending on the value of the typ field.

Note that the numbering of the struct fields continue in the sub class - it does not reset to zero.

System requirements

• .NET 2.0 or newer

License

All the C# code is licensed under the Apache License, Version 2.0.

Author, bug reports etc.

This library is written by Arne Vajhoej ([email protected]).

Bug reports, bug fixes and comments in general are welcome.

Since this is a hobby project, then I can not give any guarantees about timeline for new releases.

Version history:

1.0

Initial release (February 2011).

1.1

More advanced length providers and some new struct types (May 2013).