Custom Protocol — sgc (Generic PubSub)

Overview

This is default sub-protocol implemented using "JSONRPC 2.0" messages, every time you send a message using this protocol, a JSON object is created with the following properties:

At a glance

Features

• A messaging transport that is agnostic to the content of the payload
• Acknowledgment of messages sent.
• Implements QoS (Quality of Service) for message delivery.

Technical specification

Main properties

The principal published / public properties used to configure and drive the component. Consult the online help for the full list.

Main methods

The principal public methods exposed by the component.

Public events

The component exposes the following published events; consult the online help for full event-handler signatures.

Quick Start

Drop the component on a form, configure the properties below and activate it. The snippet that follows shows the typical sgc subprotocol client and server pair configuration.

Delphi (VCL / FireMonkey)

// --- server side
oServer := TsgcWebSocketServer.Create(nil);
oServer.Port := 80;
oServerSGC := TsgcWSPServer_sgc.Create(nil);
oServerSGC.Server := oServer;
oServer.Active := True;

// --- client side
oClient := TsgcWebSocketClient.Create(nil);
oClient.Host := '127.0.0.1';
oClient.Port := 80;
oClientSGC := TsgcWSPClient_sgc.Create(nil);
oClientSGC.Client := oClient;
oClientSGC.OnEvent := OnSGCEventEvent;
oClient.Active := True;

// publish through a named channel
oClientSGC.Subscribe('orders');
oClientSGC.Publish('{"id":42}', 'orders');

C++ Builder

// --- server side
oServer = new TsgcWebSocketServer(this);
oServer->Port = 80;
oServerSGC = new TsgcWSPServer_sgc(this);
oServerSGC->Server = oServer;
oServer->Active = true;

// --- client side
oClient = new TsgcWebSocketClient(this);
oClient->Host = "127.0.0.1";
oClient->Port = 80;
oClientSGC = new TsgcWSPClient_sgc(this);
oClientSGC->Client = oClient;
oClientSGC->OnEvent = OnSGCEventEvent;
oClient->Active = true;

oClientSGC->Subscribe("orders");
oClientSGC->Publish("{\"id\":42}", "orders");

.NET (C#)

// --- server side
oServer = new TsgcWebSocketServer();
oServer.Port = 80;
oServerSGC = new TsgcWSPServer_sgc();
oServerSGC.Server = oServer;
oServer.Active = true;

// --- client side
oClient = new TsgcWebSocketClient();
oClient.Host = "127.0.0.1";
oClient.Port = 80;
oClientSGC = new TsgcWSPClient_sgc();
oClientSGC.Client = oClient;
oClientSGC.OnEvent += OnSGCEventEvent;
oClient.Active = true;

oClientSGC.Subscribe("orders");
oClientSGC.Publish("{\"id\":42}", "orders");

Common scenarios

Each scenario shows the configuration and method calls needed to drive the component through a specific real-world flow. Every identifier below is taken from the component declaration shipped with the library.

1 · Channels, publish and broadcast

Subscribe registers the client on a named channel, Publish sends a message to every client subscribed to that channel, and Broadcast reaches every connected client, optionally narrowed to a channel. Messages delivered on a channel arrive through OnEvent, which carries both the channel name and the payload. The optional aQueue argument selects the queue level, queueLevel0 by default.

procedure TForm1.OnSGCEventEvent(Connection: TsgcWSConnection;
  const Channel, Text: string);
begin
  DoLog(Channel + ': ' + Text);
end;

oClientSGC.Subscribe('orders');
oClientSGC.Publish('{"id":42}', 'orders', '', queueLevel0);
oClientSGC.Broadcast('server going down in 5 min');
oClientSGC.UnSubscribe('orders');
oClientSGC.UnSubscribeAll;

// on the server, push to every subscriber of a channel
oServerSGC.Broadcast('{"tick":1}', 'orders');

void __fastcall TForm1::OnSGCEventEvent(TsgcWSConnection *Connection,
  const String Channel, const String Text)
{
  DoLog(Channel + ": " + Text);
}

oClientSGC->Subscribe("orders");
oClientSGC->Publish("{\"id\":42}", "orders", "", queueLevel0);
oClientSGC->Broadcast("server going down in 5 min");
oClientSGC->UnSubscribe("orders");
oClientSGC->UnSubscribeAll();

oServerSGC->Broadcast("{\"tick\":1}", "orders");

void OnSGCEventEvent(TsgcWSConnection Connection, string Channel,
  string Text)
{
  DoLog(Channel + ": " + Text);
}

oClientSGC.Subscribe("orders");
oClientSGC.Publish("{\"id\":42}", "orders");
oClientSGC.Broadcast("server going down in 5 min");
oClientSGC.UnSubscribe("orders");
oClientSGC.UnSubscribeAll();

2 · JSON-RPC calls and notifications

RPC sends a request carrying an id you generate, a method name and an optional parameter string. The server answers through OnRPC and the result comes back to the client on OnRPCResult, or on OnRPCError when the call fails. Notify is the fire-and-forget variant, it expects no answer.

// client
oClientSGC.OnRPCResult := OnRPCResultEvent;
oClientSGC.OnRPCError := OnRPCErrorEvent;
oClientSGC.RPC('call-1', 'getQuote', 'AAPL');
oClientSGC.Notify('ping');

procedure TForm1.OnRPCResultEvent(Connection: TsgcWSConnection;
  Id, Result: string);
begin
  DoLog(Id + ' = ' + Result);
end;

procedure TForm1.OnRPCErrorEvent(Connection: TsgcWSConnection; Id: string;
  ErrorCode: Integer; ErrorMessage, ErrorData: string);
begin
  DoLog(Id + ' failed: ' + ErrorMessage);
end;

// server
oServerSGC.OnRPC := OnServerRPCEvent;

procedure TForm1.OnServerRPCEvent(Connection: TsgcWSConnection;
  const ID, Method, Params: string);
begin
  if Method = 'getQuote' then
    oServerSGC.RPCResult(ID, '195.30')
  else
    oServerSGC.RPCError(ID, -32601, 'Method not found');
end;

oClientSGC->OnRPCResult = OnRPCResultEvent;
oClientSGC->OnRPCError = OnRPCErrorEvent;
oClientSGC->RPC("call-1", "getQuote", "AAPL");
oClientSGC->Notify("ping");

void __fastcall TForm1::OnRPCResultEvent(TsgcWSConnection *Connection,
  String Id, String Result)
{
  DoLog(Id + " = " + Result);
}

void __fastcall TForm1::OnRPCErrorEvent(TsgcWSConnection *Connection,
  String Id, int ErrorCode, String ErrorMessage, String ErrorData)
{
  DoLog(Id + " failed: " + ErrorMessage);
}

oServerSGC->OnRPC = OnServerRPCEvent;

void __fastcall TForm1::OnServerRPCEvent(TsgcWSConnection *Connection,
  const String ID, const String Method, const String Params)
{
  if (Method == "getQuote")
    oServerSGC->RPCResult(ID, "195.30");
  else
    oServerSGC->RPCError(ID, -32601, "Method not found");
}

oClientSGC.OnRPCResult += OnRPCResultEvent;
oClientSGC.OnRPCError += OnRPCErrorEvent;
oClientSGC.RPC("call-1", "getQuote", "AAPL");
oClientSGC.Notify("ping");

void OnRPCResultEvent(TsgcWSConnection Connection, string RPC_ID,
  string Result)
{
  DoLog(RPC_ID + " = " + Result);
}

void OnRPCErrorEvent(TsgcWSConnection Connection, string RPC_ID,
  int ErrorCode, string ErrorMessage, string ErrorData)
{
  DoLog(RPC_ID + " failed: " + ErrorMessage);
}

// server
oServerSGC.OnRPC += OnServerRPCEvent;

void OnServerRPCEvent(TsgcWSConnection Connection, string ID,
  string Method, string Params)
{
  if (Method == "getQuote")
    oServerSGC.RPCResult(ID, "195.30");
  else
    oServerSGC.RPCError(ID, -32601, "Method not found");
}

3 · QoS and transactions

QoS.Level raises the delivery guarantee, qosLevel1 asks the peer to acknowledge every message and qosLevel2 adds the two-phase exchange. Acknowledgements surface on OnAcknowledgment. StartTransaction, Commit and RollBack queue the messages sent in between, so the server only processes them once the transaction is committed. The QoS property is published on the Delphi and C++ Builder components, the .NET client exposes the transaction methods only.

oClientSGC.QoS.Level := qosLevel1;
oClientSGC.QoS.Interval := 1000;
oClientSGC.QoS.Timeout := 30000;

oClientSGC.StartTransaction('orders');
oClientSGC.Publish('{"id":1}', 'orders');
oClientSGC.Publish('{"id":2}', 'orders');
oClientSGC.Commit('orders');
// oClientSGC.RollBack('orders'); discards the queued messages

oClientSGC->QoS->Level = qosLevel1;
oClientSGC->QoS->Interval = 1000;
oClientSGC->QoS->Timeout = 30000;

oClientSGC->StartTransaction("orders");
oClientSGC->Publish("{\"id\":1}", "orders");
oClientSGC->Publish("{\"id\":2}", "orders");
oClientSGC->Commit("orders");

oClientSGC.StartTransaction("orders");
oClientSGC.Publish("{\"id\":1}", "orders");
oClientSGC.Publish("{\"id\":2}", "orders");
oClientSGC.Commit("orders");

Sources used to build this document

Every external claim links back to a primary source. The online-help references decode the canonical deep-link the company maintains for this component.