Sgcwebsockets Protocols

sgcWebSockets Subprotocols

These are the subprotocols eSeGeCe ships itself, as opposed to the third-party broker protocols in sgcwebsockets-mq. They come in client and server pairs, so both ends of the conversation are components you drop on a form, and the wire format is handled for you.

Use these when you control both ends. If you have to interoperate with someone else's broker, you want sgcwebsockets-mq instead.

When to use this skill

• Publish/subscribe over channels between your own Delphi client and server
• Call a method on the server and get a result back, over the same socket
• Keep a client-side dataset in step with a server-side one
• Send files over an existing WebSocket connection, with delivery guarantees
• Track who is present in a channel, and invite people to it
• Encrypt messages end to end so the server cannot read them
• Consume a Lightstreamer feed

Install and uses clause

All fifteen live in one unit, alongside the transport and connection classes:

uses
  sgcWebSocket,             // TsgcWebSocketClient / TsgcWebSocketServer
  sgcWebSocket_Protocols,   // the protocol components in this skill
  sgcWebSocket_Classes,     // TsgcWSConnection, handed to every event
  sgcWebSocket_Types;       // the enumerations

The binding rule

A protocol component is inert until it is attached to a transport. Client-side protocols take a client, server-side protocols take a server:

FProtocolClient.Client := FWebSocketClient;   // TsgcWSComponent_WSClient
FProtocolServer.Server := FWebSocketServer;   // TsgcWSComponent_Server

One protocol per transport, with one exception. The broker pair exists to lift that restriction: TsgcWSPClient_broker and TsgcWSPServer_broker accept other protocol components through RegisterProtocol, so several protocols share one connection. Components built to be brokered expose a Broker property to point back at it, which is how, for example, the MQTT client rides alongside others.

Before you start, ask the developer

Use a structured question tool if your host has one, for example Claude Code's AskUserQuestion. Otherwise ask in chat:

1. Do you control both ends? If the other end is someone else's broker, these components are the wrong answer, and the right skill is sgcwebsockets-mq.
2. Which protocol? They are not interchangeable. Pub/sub plus RPC is sgc, file transfer is Files, dataset sync is Dataset, and so on.
3. More than one protocol on one connection? That needs the broker pair. Retrofitting it later means rewiring both ends.
4. WAMP version? TsgcWSPClient_WAMP here is WAMP v1. WAMP2 is a different component and lives in sgcwebsockets-mq.

Components in this skill

Quickstart, the sgc protocol

Server:

uses
  sgcWebSocket, sgcWebSocket_Protocols, sgcWebSocket_Classes;

FServer := TsgcWebSocketServer.Create(Self);
FServer.Port := 5000;

FProtocol := TsgcWSPServer_sgc.Create(Self);
FProtocol.Server := FServer;

FServer.Active := True;

Client:

FClient := TsgcWebSocketClient.Create(Self);
FClient.Host := 'localhost';
FClient.Port := 5000;

FProtocol := TsgcWSPClient_sgc.Create(Self);
FProtocol.Client := FClient;
FProtocol.OnConnect := ProtocolConnect;

FClient.Active := True;

Then publish and subscribe by channel:

procedure TForm1.ProtocolConnect(Connection: TsgcWSConnection);
begin
  FProtocol.Subscribe('prices');
  FProtocol.Publish('EURUSD 1.0921', 'prices');
end;

On the server, Broadcast reaches everyone and takes optional Exclude and Include lists of connection GUIDs, so you can send to all but the sender:

FProtocol.Broadcast('server restarting', 'prices');
FProtocol.WriteData(SomeGuid, 'just for you');

RPC over the same socket

The sgc protocol carries remote calls as well as messages. The client calls, the server answers with a result or an error, both keyed by the id you pass:

// client
FProtocol.RPC('req-1', 'GetQuote', '{"symbol":"EURUSD"}');

// server, inside the RPC event
FProtocol.RPCResult('req-1', '{"bid":1.0921}');
// or
FProtocol.RPCError('req-1', 500, 'no such symbol');

Notify is the same as RPC without a reply, for when you do not need one.

The other protocols in one line each

• Files: SendFile(FileName, Size, QoS, Data, FileId). The QoS level decides whether delivery is confirmed and retried.
• Dataset: Synchronize, GetMetaData, Subscribe_all. The server sends changes, the client applies them.
• Presence: Subscribe(channel), GetMembers, Invite(channel, memberID).
• WAMP v1: Prefix(prefix, URI) to shorten topic URIs, then Subscribe(topicURI) and Call(callId, procURI, arguments).
• E2EE: SendDirectMessage(to, text) and SendGroupMessage(group, text), with CreateGroup, JoinGroup and DeleteGroup for the group side.
• Lightstreamer: set AdapterSet and LightstreamerOptions, then handle OnLightstreamerUpdate, OnLightstreamerSnapshot and the rest.

Things that catch people out

• A protocol with no transport assigned fails silently. Nothing raises, nothing connects, because the component simply never had a socket.
• Client and server must run the same protocol. A TsgcWSPClient_sgc against a plain TsgcWebSocketServer with no protocol component will connect at the WebSocket level and then do nothing useful.
• Subscribe after the protocol connects, not immediately after setting Active := True on the transport.
• aGuid throughout these APIs is the connection identifier, not a message id. It is how you address one specific client from the server.
• The WAMP component here is v1. Do not mix it up with WAMP2, which is a separate component in a separate skill.

Routing

• Find a component: reference/components-index.md lists every component, its unit, and its edition, grouped by Reg module.
• Uses clause: add the component's unit: value (shown on its API page) to your uses clause. Nothing compiles without it.
• API detail: reference/api/<Component>.md has the Properties, Events and Methods, each in both Delphi and C++Builder form.
• Option / enum / event types: property and event types link to reference/types/<TypeName>.md, which documents the sub-properties of option classes, the values of enums, and the parameter list of event handlers.
• Examples: examples/index.md is the full demo catalog; examples/<Component>.md is a focused, real usage snippet for the most-used components.
• Concepts: concepts/overview.md (getting started + uses-clause rule) and concepts/editions-and-features.md (which components your edition includes).
• Bundled resources: concepts/resources.md lists the browser-side assets (JavaScript, HTML, CSS) the server components serve or embed, so a browser client works without an external CDN.
• Version history: reference/history.md lists what changed in each sgcWebSockets release.

Editions

Components are gated by edition (Professional, Enterprise, All-Access) or by a feature define. Check the edition column in the components index, or concepts/editions-and-features.md, before relying on a component.

Only public and published members are documented. Method bodies, private fields and protected members are intentionally not included.