LiteByteCapsule 1.1.6

LiteByteCapsule is a solution/library to encapsulate your byte array packages before sending them over certain protocols (TCP-IP, Socket, API, etc.)

Usage

![alt text][diagram]

<a name="constants"></a> About encapsulation constants

Both encapsulation and decapsulation actions require encapsulation constants to be present. Encapsulation constants are a variable type that is defined in the package (CapsuleConstants).

CapsuleConstants Class

CapsuleConstants class consists:

Incase you get lazy and don't want to define bunch of CapsuleConstants by hand, you may refer to :

CapsuleConstants.GenerateCapsulationConstants(int amount) is a static method to generate specified amount of CapsuleConstants instances. Returns Stack<CapsuleConstant> which could be used to create LiteByteCapsule instance.

<a name="constructors"></a> Constructors

For encapsulation or decapsulation, you have to create LiteByteCapsule class instance using diverse constructors.

LiteByteCapsule()

This constructor is used in order to encapsule/decapsulate byte array packages using SmartCapsule technique.

Smart encapsulation

*byte[] is your actual byte array.

**CRC32C is CRC32C calculation of your actual byte array.

LiteByteCapsule(Stack<CapsuleConstant> constants)

This constructor is used in order to encapsule/decapsulate byte array packages by placing CapsuleConstants into defined positions.

Encapsulation by CapsuleConstant Stack

*Head constants: CapsuleConstants in the stack provided as parameter, which has head=true value

**byte[] is your actual byte array.

***Head constants: CapsuleConstants in the stack provided as parameter, which has head=false value

LiteByteCapsule(byte[] constantFirstPart, byte[] constantLastPart)

This constructor is used in order to encapsule/decapsulate byte array packages by putting constantFirstPart array to the start of the capsule and constantLastPart array to end of the capsule.

Encapsulation by two byte arrays

*byte[] is your actual byte array.

<a name="encapsulation"></a> Encapsulation

Simply use ConvertToSyntax(byte[] infactData) method on your LiteByteCapsule instance.

LiteByteCapsule lite=new LiteByteCapsule();

//or LiteByteCapsule lite = new LiteByteCapsule(CapsuleConstant.GenerateCapsulationConstants(5));

/*
or 
Stack<CapsulationConstant> constants=new Stack<CapsulationConstant>();
LiteByteCapsule lite = new LiteByteCapsule(constants);
*/

/*
or
byte[] head=....
byte[] tail=...
LiteByteCapsule lite=new LiteByteCapsule(head, tail);
*/

//Then just pass your byte array to ConvertToSyntax method:
byte[] myPackage=[12,255,234,116];
byte[] capsule=lite.ConvertToSyntax(myPackage);
//capsule is the encapsulated byte array.

<a name="exporting"></a> Exporting Encapsulation Constants

After encapsulation process, you might want to send your export your encapsulation constants to the receiver of the package/capsule so that the receiver can create LiteByteCapsule instance and do decapsulate your package according to your encapsulation constants.

//Use your previously created LiteByteCapsule instance:

string json=lite.CapsulationConstantsJSONString();

//Then send it to your listener/receiver through an api/websocket/endpoint etc. 
//Receiver will have to parse the json and use it to create LiteByteCapsule instance.

<a name="decapsulation"></a> Decapsulation

//Create your LiteByteCapsule according to the Capsule Constants provided by the package sender.

Stack<CapsuleConstant> constants = JsonConvert.DeserializeObject<Stack<CapsuleConstant>>(a);

LiteByteCapsule lite=new LiteByteCapsule(constants);

byte[] incomingPackage=....

byte[] actualPackage=lite.CheckSyntax(incomingPackage);

//returns null if the package provided(incomingPackage) is an imposter/doesn't fit to the sequence expected.

<a name="instance-util"></a> Instance utilities/helpers

//Stack<CapsuleConstant> constants=...

LiteByteCapsule lite=new LiteByteCapsule(constants);

//From your instance you have access to these utilities:

//CapsulationConstantsJSONString: For converting the encapsulation constants to JSON string

string json=lite.CapsulationConstantsJSONString();

//GetCapsulationConstants: To get your stack of encapsulation constants that you provided earlier to create an instance of LiteByteCapsule

Stack<CapsuleConstant<CapsuleConstant> constants=lite.GetCapsulationConstants();

<a name="static-util"></a> Static utilities/helpers

//Generate a random byte array 
byte[] package=LiteByteCapsule.GetRandomPackage(20);

//Convert a byte array to string
string readableFormat=LiteByteCapsule.ConvertToString(package);

//Generate CRC32C Hash/Checksum of a byte array
string hash=LiteByteCapsule.GenerateCRC32C(package);

//Add CRC32C calculation to end of an array (4 elements)
byte[] capsule=LiteByteCapsule.AddCRC32CToEnd(package);


//Check CRC32C integrity of a package (warning, this will expect that the given array has last 4 elements as CRC32C
byte[] actualPackage=LiteByteCapsule.CheckCRC32CIntegrity(package);