SRO.Net.BIDHASP Framework

SRO.Net.BIDHASP is a .NET Framework library that implements a Bidirectional Hub-and-Spoke Protocol (BIDHASP) for inter-process communication. It provides a structured, event-driven messaging architecture where a central hub server manages connections from multiple spoke clients, with full support for raw sockets, plain TCP streams, and TLS-encrypted streams.

Table of Contents

• Architecture Overview
• Projects
• Getting Started
  • Configuration
  • Hub Setup
  • Spoke Setup
• Wire Protocol
• Sending and Receiving Data
• Events
• Communication Channel Types
• TLS Configuration
• Message Levels
• API Reference

Architecture Overview

BIDHASP follows a hub-and-spoke topology:

  [Spoke A] ──┐
  [Spoke B] ──┼──► [Hub]
  [Spoke C] ──┘

• The Hub is a TCP server that listens for incoming connections, assigns each connected spoke a unique integer ID, and can broadcast messages to all connected spokes.
• A Spoke is a TCP client that connects to the hub, registers itself with a hostname-derived name, and can send and receive typed data packets.

All data is exchanged as TransactedData packets — fixed-header, variable-payload frames that carry a BasicDataType (String or Binary), a DetailedDataType (e.g., PlainString, JSON, Int32), an application-defined MessageType, and the payload bytes.

Projects

Getting Started

Configuration

Before creating a HubManager or SpokeManager, initialize the APIConfigurationManager. The configuration is read from a JSON file named {appname}.config.json.

Quick-start (development only — no TLS):

// Uses defaults: port 4800, localhost, plain Stream channel.
// Creates bidhasp.config.json in the user profile folder if it does not exist.
APIConfigurationManager.Initialize();

Named application config from user profile directory:

APIConfigurationManager.Initialize("myapp");
// Loads %USERPROFILE%\myapp.config.json

Named application config from an explicit directory:

APIConfigurationManager.Initialize(@"C:\myapp\config", "myapp");
// Loads C:\myapp\config\myapp.config.json

Configuration file structure (myapp.config.json):

{
  "HubHost": "localhost",
  "Port": 4800,
  "CommunicationChannelType": "Stream",
  "CertificateFilePath": "bidhasp_cert.pfx",
  "KeyFilePath": "bidhasp_key.pem",
  "Thumbprint": "",
  "SubjectName": "",
  "PathIsRelativeToProfileDirectory": true,
  "PrivateKeyPassword": ""
}

Hub Setup

using SRO.Net.BIDHASP.Core;
using SRO.Net.BIDHASP.Hub;

// 1. Initialize configuration.
APIConfigurationManager.Initialize();

// 2. Create the hub manager.
HubManager hub = new HubManager();        // uses the configured port (default: 4800)
// — or —
HubManager hub = new HubManager(5000);   // explicit port override

// 3. Wire up logging.
hub.MessagePosted += (sender, e) =>
{
    Console.WriteLine($"[{e.Level}] {e.Message}");
    if (e.Cause != null) Console.WriteLine(e.Cause);
};

// 4. Handle spoke lifecycle events.
hub.SpokeWorkflowEvent += (sender, e) =>
{
    if (e.EventType == SpokeWorkflowEventType.ASSIGNED_ID)
    {
        Console.WriteLine($"Spoke connected — ID: {e.Spoke.Id}, Name: {e.Spoke.Name}");

        // Subscribe to per-spoke data events.
        e.Spoke.ReceiveStringData += (s, args) =>
            Console.WriteLine($"String from spoke {args.Id} (type {args.MessageType}): {args.Data}");

        e.Spoke.ReceiveBinaryData += (s, args) =>
            Console.WriteLine($"Binary from spoke {args.Id} (type {args.MessageType}): {args.Data.Length} bytes");
    }
};

// 5. Start the hub — binds the socket and begins accepting connections.
hub.Start();

// 6. Broadcast to all connected spokes.
hub.Send(messageType: 1, data: "Hello, all spokes!");
hub.Send(messageType: 2, data: new byte[] { 0x01, 0x02, 0x03 });

// 7. Send to a specific spoke by ID.
Spoke target = hub.SpokeUnits.FirstOrDefault(s => s.Id == 3);
target?.Send(messageType: 1, stringInfo: "Hello, spoke 3 only!");

// 8. Stop the hub — closes all connections.
hub.Stop();

Spoke Setup

using SRO.Net.BIDHASP.Core;
using SRO.Net.BIDHASP.Spoke;

// 1. Initialize configuration.
APIConfigurationManager.Initialize();

// 2. Create the spoke manager.
SpokeManager spokeManager = new SpokeManager();
// — or —
SpokeManager spokeManager = new SpokeManager(hubHostname: "192.168.1.10", port: 4800);

// 3. Wire up logging.
spokeManager.MessagePosted += (sender, e) =>
    Console.WriteLine($"[{e.Level}] {e.Message}");

// 4. Subscribe to data events on the hub facade.
spokeManager.Hub.ReceiveStringData += (sender, e) =>
    Console.WriteLine($"Received string from hub (type {e.MessageType}): {e.Data}");

spokeManager.Hub.ReceiveBinaryData += (sender, e) =>
    Console.WriteLine($"Received binary from hub (type {e.MessageType}): {e.Data.Length} bytes");

// 5. Subscribe to the ID-assignment event (fired once, shortly after Connect).
spokeManager.Hub.AssignedIdReceived += (sender, e) =>
    Console.WriteLine($"Hub assigned this spoke ID: {e.AssignedId}");

// 6. Connect to the hub (synchronous — includes a brief settlement delay).
spokeManager.Hub.Connect();

// 7. Send data to the hub.
spokeManager.Hub.Send(messageType: 1, stringInfo: "Hello, hub!");
spokeManager.Hub.Send(messageType: 2, bytes: new byte[] { 0xAA, 0xBB });

Wire Protocol

Every message is framed as a TransactedData packet with a fixed 12-byte header followed by a variable-length payload:

 Offset  0       4       6    7       8          12     12+N
         +-------+-------+----+-------+----------+------+
         |  Id   |MsgType|BDT | DDT   |PayloadSz |  ... |
         | int32 |uint16 |byte| byte  |  uint32  |  N   |
         +-------+-------+----+-------+----------+------+
         |<------------- 12-byte header -------->|<pay->|

TransactedData can be serialized with ToByteArray() and deserialized with FromByteArray(byte[]). The payload size can be extracted from the header alone using GetHeaderPayloadSize(byte[]).

Sending and Receiving Data

Sending

Both HubManager and BIDCommunicationsUnitBase (the base for Spoke and the spoke-side Hub facade) expose the same family of send methods:

Note: HubManager.Send() broadcasts to all connected spokes. To target a specific spoke, call Send() directly on the Spoke instance retrieved from HubManager.SpokeUnits.

Receiving

Subscribe to the ReceiveStringData or ReceiveBinaryData events on the relevant object:

unit.ReceiveStringData += (sender, e) =>
{
    // e.Id              — sender's unit ID
    // e.MessageType     — application-defined message type
    // e.DetailedDataType — e.g. PlainString, JSONSerialization
    // e.Data            — the string payload
};

unit.ReceiveBinaryData += (sender, e) =>
{
    // e.Id              — sender's unit ID
    // e.MessageType     — application-defined message type
    // e.DetailedDataType — e.g. ByteArray, Int32, Double …
    // e.Data            — the raw byte array
};

Events

HubManager Events

SpokeWorkflowEventType Values

BIDCommunicationsUnitBase / Spoke / Hub Events

Hub (Spoke-side facade) Additional Event

Communication Channel Types

TLS Configuration

When CommunicationChannelType is TLSStream, the certificate is resolved in the following priority order:

1. Thumbprint — Searches the CurrentUser\My and LocalMachine\My certificate stores.
2. Subject Name — Searches the same stores by subject name.
3. File-based:
   • .pfx / .p12 — PKCS#12 bundle containing the certificate and private key.
   • PEM certificate paired with a separate PEM private-key file (KeyFilePath). If the private key is encrypted, set PrivateKeyPassword in the configuration file.

The hub authenticates as the TLS server using the loaded certificate; spokes authenticate as TLS clients against the configured HubHost. Both TLS 1.2 and TLS 1.3 are accepted.

Message Levels

BIDHASPMessageLevel categorizes messages surfaced by the MessagePosted event:

API Reference

APIConfigurationManager (static — SRO.Net.BIDHASP.Core)

HubManager (SRO.Net.BIDHASP.Hub)

SpokeManager (SRO.Net.BIDHASP.Spoke)

Hub — Spoke-side facade (SRO.Net.BIDHASP.Spoke)

DetailedDataType Enum (SRO.Net.BIDHASP.Core)

CommunicationsUnitState Enum (SRO.Net.BIDHASP.Core)

BIDCommunicationsUnitBase Constants (SRO.Net.BIDHASP.Core)