LiteByteCapsule 1.1.6

LiteByteCapsule is a NuGet package to apply capsulation for byte arrays which is used for sending them over TCP IP protocol or socket.

Install-Package LiteByteCapsule -Version 1.1.6
dotnet add package LiteByteCapsule --version 1.1.6
<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
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

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&lt;CapsuleConstant&gt; 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&lt;CapsuleConstant&gt; 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);

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&lt;CapsuleConstant&gt; 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&lt;CapsuleConstant&gt; 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);

Release Notes

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.

This package is not used by any popular GitHub repositories.

Version History

Version Downloads Last updated
1.1.6 94 7/31/2019
1.1.5 93 7/22/2019
1.1.0 94 7/19/2019
1.0.8 97 7/17/2019
1.0.7 96 7/17/2019
1.0.6 97 7/17/2019
1.0.5 97 7/17/2019
1.0.4 97 7/17/2019
1.0.3 98 7/16/2019
1.0.2 99 7/16/2019
1.0.1 100 7/16/2019
1.0.0 99 7/16/2019