C# binding

​

Install

git clone --branch v0.32.0 --depth 1 https://github.com/Offline-Protocol/offline-protocol-sdk.git
dotnet add reference offline-protocol-sdk/bindings/csharp/src/OfflineProtocol.Sdk/OfflineProtocol.Sdk.csproj

​

Quick start

using OfflineProtocol.Sdk;
using OfflineProtocol.Sdk.Config;
using OfflineProtocol.Sdk.LocalApi;

Console.WriteLine(ProtocolEngine.LibraryVersion); // "0.32.0"

// Name the fields the definition leaves without a default; the rest take the engine's.
var config = new ProtocolConfig
{
    AppId = "com.example.mesh",
    Profile = "desk-01",
    BleEnabled = false,
    WifiDirectEnabled = false,
    InternetEnabled = true,
    ReticulumEnabled = false,
    NostrEnabled = false,
    PreferOnline = false,
    InitialTtl = 8,
    EncryptionEnabled = true,
    AutoKeyExchange = true,
    StorePending = true,
    MaxPendingPerPeer = 64,
    MaxPendingGlobal = 4096,
    PendingTtlMs = 60_000,
    OverflowPolicy = OverflowPolicy.DropOldest,
};

await using var engine = await ProtocolEngine.CreateAsync(config);
await engine.InitializeMlsWithFileStoresAsync(mlsDir, stateDir, storeKeyBase64);
await engine.SetEventCallbackAsync(json => Console.WriteLine(json));
await engine.StartAsync();

Console.WriteLine(await engine.LocalAddressAsync()); // "off1..."
await engine.SendMessageAsync(LocalApiParams.SendMessage(peerAddress, "hello"));

var subId = await engine.Services.SubscribeServiceAsync(
    """{"provider":"off1...","service_id":"equipment-status.v1","topic":"battery","mode":"Latest","params":"","keys":[]}""");

​

Storage

​

Threads, events and callbacks

• One engine thread. Every call for an engine runs on its own .NET thread behind a bounded queue (512 calls by default). Await each call; a slow call such as StartAsync delays every call queued behind it. Cancelling a call ends your wait, not a call already queued.
• Events off the engine thread. SetEventCallbackAsync delivers each event as JSON on a dedicated delivery thread. A handler that throws is counted in EventHandlerFailureCount and never ends the process. PollEventAsync reads the same events without a callback. Keep handlers short and never call the same engine synchronously from one.
• Transport callbacks. SetBleTransportCallbackAsync, SetWifiDirectTransportCallbackAsync, SetReticulumTransportCallbackAsync and SetNostrTransportCallbackAsync signal that a carrier has outbound frames. Drain them with the generated methods, such as BleGetNextFragmentAsync, until the queue answers null. Install them before StartAsync.
• Dispose before exit. WinUI, WPF and MAUI hosts call DisposeAsync before the application shuts down, so telemetry flushes and transports stop cleanly.

​

What your host provides

• Transports. The radios and sockets, through the transport callbacks and the generated transport methods.
• Storage. The built-in file stores or two providers, as above.
• Telemetry lifecycle. If you enable telemetry with EnableTelemetryAsync, the library fills os and the binding fills os_major. Call NotifyAppStateAsync when a desktop app leaves and returns to the foreground.

​

Reference

• C# binding README: building, testing and the consumer check.
• C# binding contract: the engine thread, events, storage providers, telemetry, typed configuration and transport callbacks.
• C binding: the C API the binding calls.