LiteByteCapsule 1.1.6

dotnet add package LiteByteCapsule --version 1.1.6
NuGet\Install-Package LiteByteCapsule -Version 1.1.6
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="LiteByteCapsule" Version="1.1.6" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add LiteByteCapsule --version 1.1.6
#r "nuget: LiteByteCapsule, 1.1.6"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install LiteByteCapsule as a Cake Addin
#addin nuget:?package=LiteByteCapsule&version=1.1.6

// Install LiteByteCapsule as a Cake Tool
#tool nuget:?package=LiteByteCapsule&version=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:

Name Type Cool
val byte Value property of an CapsuleConstant instance. Byte value for constant.
position int Position of the constant related to the start position parameter(head). E.g: if position is:0 and head=true, this constant will be the first element in the capsule.
head bool Property to indicate counting for position from start(head) or counting from the end(tail) of the capsule. E.g:Head:false, position:0 will be the last element of the capsule.

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

First element In between Last 4 elements
0 byte[] * CRC32C **

*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(start) In between Tail(end)
Head constants * byte[] ** Tail constants ***

*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

Head(start) In between Tail(end)
constantFirstPart[] byte[] * Tail constantFirstPart

*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);
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.1.6 630 7/31/2019
1.1.5 512 7/22/2019
1.1.0 523 7/19/2019
1.0.8 526 7/17/2019
1.0.7 523 7/17/2019
1.0.6 539 7/17/2019
1.0.5 510 7/17/2019
1.0.4 513 7/17/2019
1.0.3 519 7/16/2019
1.0.2 533 7/16/2019
1.0.1 511 7/16/2019
1.0.0 506 7/16/2019

Exception handlings has been incresed, exceptions are being thrown in certain cases in this vers.
Unit tests are completed successfully. Code coverage >95%
Check Github repo for code coverage status.


Implementation of random constant stack is ready for test.