Sgcwebsockets Core

sgcWebSockets Core

sgcWebSockets Core is the WebSocket client and the WebSocket servers: the pieces you reach for first. Everything else in the suite either rides on top of these components or plugs into them.

When to use this skill

• Open a WebSocket connection from a Delphi or C++Builder application
• Host a WebSocket server, with or without HTTP on the same port
• Serve HTTP and WebSocket together, including static files and REST endpoints
• Put a WebSocket server behind a proxy or a load balancer
• Keep a connection alive across network drops, with heartbeat and watchdog
• Protect a server with an IP firewall, rate limiting, a circuit breaker or API keys
• Run several server nodes as one cluster
• Use the Windows HTTP.sys stack instead of Indy for the server

For a specific subprotocol (MQTT, STOMP, AMQP, WAMP) or an exchange feed, this is the wrong skill. Load sgcwebsockets-mq, sgcwebsockets-protocols or sgcwebsockets-exchanges instead. They build on the client documented here.

Install and uses clause

The library is installed as design-time packages in the IDE, so the components appear on the palette. Nothing compiles, however, until the right unit is in your uses clause. Every API page in this skill states its unit: at the top.

For the client and the servers documented here that unit is sgcWebSocket:

uses
  sgcWebSocket, sgcWebSocket_Classes, sgcWebSocket_Types;

sgcWebSocket_Classes gives you TsgcWSConnection, which every event hands you. sgcWebSocket_Types gives you the enumerations used by the options.

Components are gated by edition. Check the edition column in reference/components-index.md before relying on one.

Before you start, ask the developer

If your host offers a structured question tool, for example Claude Code's AskUserQuestion, use it. Otherwise ask in chat before writing code. Getting these wrong produces code that compiles and then fails at runtime:

1. Client or server? They are different components with different options.
2. TLS? TLS := True also needs a TLS handler decision. On Windows the SChannel handler needs no DLLs, OpenSSL needs the DLLs deployed next to the executable. Ask which they want before writing the setup.
3. Which Delphi version and platform? Some options are version gated, and the TLS handler choice differs on Linux, Android and iOS.
4. Blocking or event driven? Connect blocks until connected or timeout. Setting Active := True returns immediately and reports through OnConnect. Most GUI code wants the second.
5. Does the server also need to serve HTTP? If yes, use TsgcWebSocketHTTPServer, not TsgcWebSocketServer. Switching later means rewriting the setup.

Components in this skill

Quickstart, client

uses
  sgcWebSocket, sgcWebSocket_Classes;

procedure TForm1.FormCreate(Sender: TObject);
begin
  FClient := TsgcWebSocketClient.Create(Self);
  FClient.Host := 'echo.websocket.org';
  FClient.Port := 443;
  FClient.TLS := True;
  FClient.OnConnect := ClientConnect;
  FClient.OnMessage := ClientMessage;
  FClient.OnDisconnect := ClientDisconnect;
  FClient.OnError := ClientError;
  // returns immediately, OnConnect fires when the handshake completes
  FClient.Active := True;
end;

procedure TForm1.ClientConnect(Connection: TsgcWSConnection);
begin
  FClient.WriteData('hello');
end;

procedure TForm1.ClientMessage(Connection: TsgcWSConnection; const Text: string);
begin
  Memo1.Lines.Add(Text);
end;

When you have a full endpoint, URL is a write-only shortcut that populates Host, Port, TLS and the query parameters in one assignment: FClient.URL := 'wss://echo.websocket.org/socket?token=abc';. It is write-only, so you cannot read it back; keep your own copy if you need the value later.

Quickstart, server

uses
  sgcWebSocket, sgcWebSocket_Classes;

procedure TForm1.FormCreate(Sender: TObject);
begin
  FServer := TsgcWebSocketServer.Create(Self);
  FServer.Port := 5000;
  FServer.OnConnect := ServerConnect;
  FServer.OnMessage := ServerMessage;
  FServer.Active := True;
end;

procedure TForm1.ServerMessage(Connection: TsgcWSConnection; const Text: string);
begin
  // echo back to the sender
  Connection.WriteData(Text);
  // or broadcast to everyone
  FServer.Broadcast(Text);
end;

Surviving a dropped connection

This is the most common support question, so set it up from the start. The watchdog reconnects, the heartbeat detects a half-open socket that TCP has not noticed yet. They solve different problems and are usually both wanted:

FClient.WatchDog.Enabled := True;
FClient.WatchDog.Interval := 10;   // seconds between reconnect attempts
FClient.WatchDog.Attempts := 0;    // how many times to retry

FClient.HeartBeat.Enabled := True;
FClient.HeartBeat.Interval := 30;  // seconds between pings
FClient.HeartBeat.Timeout := 0;

Things that catch people out

• Active := True does not mean connected. Wait for OnConnect. Writing in the line after setting Active usually raises "socket not connected".
• Events arrive on the connection's own thread, not the main thread. Touching VCL or FMX controls directly from an event will eventually corrupt the UI. Marshal to the main thread with TThread.Queue or Synchronize.
• OnMessage gives you text frames. Binary frames arrive on OnBinary, and a message split across frames arrives on OnFragmented unless you let the library reassemble it.
• A server that must also answer plain HTTP requests, serve static files or expose REST endpoints needs TsgcWebSocketHTTPServer. TsgcWebSocketServer handles the WebSocket protocol only.

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.