sgcWebSockets in vijf minuten

Je hebt de bibliotheek geïnstalleerd en het palet is zichtbaar. Deze pagina brengt je van daaruit naar een server die een verbinding accepteert en een client die een bericht verstuurt en het antwoord leest. Alles hieronder komt uit een demo die in de download zit, dus je kunt het project openen in plaats van alles over te typen.

Delphi 7 tot en met RAD Studio 13
Windows, Linux, macOS, iOS, Android
Client vanaf Standard, server vanaf Professional

Wat het eerste voorbeeld nodig heeft

Twee niet-visuele componenten, één unit in de uses-clausule en nog een extra unit voor de parametertypen van de event handlers.

Clientcomponent

TsgcWebSocketClient, gedeclareerd in sgcWebSocket.pas en geregistreerd op de palettabpagina SGC WebSockets. Stel Host en Port in en daarna Active.

Servercomponent

TsgcWebSocketServer, dezelfde unit, dezelfde palettabpagina. Stel Port in en daarna Active. De server luistert, upgradet de handshake en roept OnConnect aan.

De tweede unit

Elke gebeurtenis geeft je een TsgcWSConnection, die in sgcWebSocket_Classes.pas staat. De demo's schrijven uses sgcWebSocket, sgcWebSocket_Classes; en dat moet jij ook doen.

Platforms

Geen van beide units heeft een platformbeveiliging en beide componenten zijn geregistreerd met ComponentPlatforms(0), dus VCL-, FMX-, console- en servicedoelen compileren allemaal. Een FireMonkey-clientdemo zit bij de download.

Vereisten en edities

De editiekolom noemt de define die de code echt afschermt, met het regelnummer in Source/sgcVer.inc.

Onderdeel Waarde
IDE Delphi 7 tot en met RAD Studio 13 en C++Builder 2007 tot en met 13. Eén packagegroep per IDE-versie onder Packages\.
Uses-clausule sgcWebSocket voor de componenten, sgcWebSocket_Classes voor TsgcWSConnection.
Clienteditie TsgcWebSocketClient staat in {$IFDEF SGC_WS_CLIENT}. SGC_WS_CLIENT wordt gedefinieerd op regel 697, binnen het {$IFDEF SGC_EDT_STD}-blok dat loopt van regel 675 tot regel 724. Dus Standard en hoger.
Servereditie TsgcWebSocketServer staat rechtstreeks in {$IFDEF SGC_EDT_PRO} en de palettregistratie in sgcWebSocket_Reg.pas staat binnen dezelfde beveiliging. Het Professional-functieblok loopt van regel 727 tot regel 758. Dus Professional en hoger. Een Standard-licentie geeft je de client, niet de server.
Palettabpagina Geregistreerd onder {$IFDEF SGC_PACK_WEBSOCKETS}, gedefinieerd op regel 852.
Platforms Geen platformbeveiliging op unitniveau in sgcWebSocket.pas, sgcWebSocket_Client.pas of sgcWebSocket_Server.pas. Windows haalt de unit Windows alleen voorwaardelijk binnen, meer niet.

Weet je niet welke editie je gebruikt? Open Source/sgcVer.inc en bekijk de eerste vijf regels. De SGC_EDT_*-defines daar zijn cumulatief: All-Access definieert ze allemaal en Standard alleen de eerste twee.

Installeer en controleer het palet

Vijf stappen van het zipbestand naar een component die je op een formulier kunt plaatsen. Compileer het runtime-package voordat je het designtime-package installeert, want het tweede verwijst naar het eerste.

1. Uitpakken

Pak de download uit in een map naar keuze. De rest van deze pagina noemt die map {$DIR}. De mappen Source\, Packages\, Demos\ en lib*\ staan er allemaal onder.

2. Bibliotheekpad

Tools, Options, Library. Voeg {$DIR}\source toe en de map die bij je IDE hoort, bijvoorbeeld {$DIR}\libD13\$(Platform) op RAD Studio 13 of {$DIR}\libD12\$(Platform) op 12.

3. De packages bouwen

Open {$DIR}\Packages\sgcWebSocketsD13.groupproj voor jouw IDE-versie. Compileer eerst sgcWebSocketsD13.dpk en installeer daarna dclsgcWebSocketsD13.dpk. C++Builder gebruikt de .cbproj-bestanden in dezelfde map.

4. Het palet controleren

Er verschijnt een nieuwe pagina met de naam SGC WebSockets. In een Standard-build bevat die TsgcWebSocketClient. Vanaf Professional bevat die ook TsgcWebSocketServer, TsgcWebSocketHTTPServer, TsgcWebSocketProxyServer en TsgcWebSocketLoadBalancerServer.

5. Een demo openen

Open, voordat je iets schrijft, {$DIR}\Demos\01.WebSocket_Quick_Start\01.Server_and_Client_Chat. Dit is het kleinste werkende paar in de bibliotheek en de onderstaande code komt daaruit.

Een server en een client, in ongeveer twintig regels

Start de server, start de client, verstuur een string. Het servertabblad luistert op een poort; het clienttabblad maakt er verbinding mee en schrijft één bericht.

uServerChat.pas
uses
  Classes, SysUtils,
  // sgc
  sgcWebSocket, sgcWebSocket_Classes;

procedure TfrmServerChat.btnStartClick(Sender: TObject);
begin
  WSServer.Port := 5418;
  WSServer.Active := True;
  memoLog.Lines.Add('#started');
end;

procedure TfrmServerChat.WSServerConnect(Connection: TsgcWSConnection);
begin
  memoLog.Lines.Add('Connected: ' + Connection.IP);
end;

procedure TfrmServerChat.WSServerDisconnect(Connection: TsgcWSConnection;
  Code: Integer);
begin
  memoLog.Lines.Add('Disconnected (' + IntToStr(Code) + '): ' + Connection.IP);
end;

procedure TfrmServerChat.WSServerMessage(Connection: TsgcWSConnection;
  const Text: string);
begin
  memoLog.Lines.Add(Text);
  // send it straight back, so the client has something to read
  Connection.WriteData('echo: ' + Text);
end;

Plaats TsgcWebSocketServer op het formulier, geef het de naam WSServer en laat de IDE de vier handlers genereren vanuit de Object Inspector. Connection.IP en Connection.WriteData komen allebei uit TsgcWSConnection, en daarom staat sgcWebSocket_Classes in de uses-clausule.

uClientChat.pas
uses
  Classes, SysUtils,
  // sgc
  sgcWebSocket, sgcWebSocket_Classes;

procedure TfrmClientChat.btnStartClick(Sender: TObject);
begin
  WSClient.Host := 'localhost';
  WSClient.Port := 5418;
  WSClient.TLS := False;
  WSClient.Active := True;
end;

procedure TfrmClientChat.btnSendClick(Sender: TObject);
begin
  if WSClient.Active then
    WSClient.WriteData('Hello from Delphi')
  else
    raise Exception.Create('Not connected');
end;

procedure TfrmClientChat.WSClientConnect(Connection: TsgcWSConnection);
begin
  memoLog.Lines.Add('#connected');
end;

procedure TfrmClientChat.WSClientMessage(Connection: TsgcWSConnection;
  const Text: string);
begin
  memoLog.Lines.Add(Text);
end;

Draai eerst het serverproject en daarna dit project. #connected verschijnt in het clientlogboek en echo: Hello from Delphi komt terug op OnMessage. Die heen-en-terugreis is de hele snelstart.

uConsole.pas
program WSConsoleClient;

{$APPTYPE CONSOLE}

uses
  Classes, SysUtils,
  // sgc
  sgcWebSocket, sgcWebSocket_Classes;

type
  TChatHandler = class
    procedure DoConnect(Connection: TsgcWSConnection);
    procedure DoMessage(Connection: TsgcWSConnection; const Text: string);
  end;

procedure TChatHandler.DoConnect(Connection: TsgcWSConnection);
begin
  Writeln('#connected');
end;

procedure TChatHandler.DoMessage(Connection: TsgcWSConnection;
  const Text: string);
begin
  Writeln('Server says: ', Text);
end;

var
  oClient: TsgcWebSocketClient;
  oHandler: TChatHandler;
begin
  oHandler := TChatHandler.Create;
  oClient := TsgcWebSocketClient.Create(nil);
  try
    oClient.Host := 'localhost';
    oClient.Port := 5418;
    oClient.WatchDog.Enabled := True;   // reconnect on its own

    // assign the handlers BEFORE Active, or the first
    // OnConnect can fire with nothing attached
    oClient.OnConnect := oHandler.DoConnect;
    oClient.OnMessage := oHandler.DoMessage;

    oClient.Active := True;
    oClient.WriteData('Hello from Delphi');
    Readln;
  finally
    oClient.Free;
    oHandler.Free;
  end;
end.

De client draait in een eigen thread, dus een consoleprogramma moet de hoofdthread in leven houden. Daar dient de Readln voor.

De tabbladen Server en Client zijn de meegeleverde demo Demos\01.WebSocket_Quick_Start\01.Server_and_Client_Chat, zonder de code voor de selectievakjes en invoervelden van de demo. Het derde tabblad bevat dezelfde aanroepen, maar dan voor componenten die tijdens runtime worden aangemaakt in plaats van op een formulier te worden geplaatst.

Bewijs de heen-en-terugreis

Vier gebeurtenissen vertellen je alles over de eerste run en je wilt ze alle vier hebben gekoppeld voordat je verdergaat.

Active

Op de server slaagt Active := True of het veroorzaakt een exception. Als de poort bezet is, merk je dat hier en niet drie stappen later.

OnConnect

procedure(Connection: TsgcWSConnection). Wordt aan beide kanten aangeroepen. Op de server vertelt Connection.IP wie er is binnengekomen; op de client is het het bewijs dat de handshake is geüpgraded.

OnMessage

procedure(Connection: TsgcWSConnection; const Text: string). De echo die op de client terugkomt, bewijst de heen-en-terugreis end-to-end.

OnError en OnException

procedure(Connection: TsgcWSConnection; const Error: string) and procedure(Connection: TsgcWSConnection; E: Exception). Koppel ze allebei. Zonder deze handlers is een fout stil en lijkt het alsof er niets is gebeurd.

Wat er de eerste keer meestal misgaat

Bijna elk probleem bij de eerste run is een van deze zes.

TsgcWebSocketServer staat niet op het palet

De serverklasse wordt alleen gecompileerd als SGC_EDT_PRO is gedefinieerd, op regel 130 van sgcWebSocket.pas, en wordt alleen binnen dezelfde beveiliging geregistreerd. In een Standard-build is de client er wel en de server niet. Dat is licentiebeleid, geen kapotte installatie.

Niet-gedeclareerde identifier TsgcWSConnection

De componenten staan in sgcWebSocket, het verbindingsobject staat in sgcWebSocket_Classes. Voeg de tweede unit toe aan de uses-clausule. Elke meegeleverde demo heeft beide.

De client verbindt en valt daarna weg

Stel WatchDog.Enabled := True in, zodat een weggevallen verbinding zichzelf herstelt, en behandel OnError en OnException. Een stille verbreking zonder handler lijkt alsof er niets is gebeurd.

Er komt niets aan bij de server

Controleer of de client echt actief is voordat je schrijft. WriteData op een inactieve client doet niets nuttigs, en daarom test de demo if WSClient.Active then voordat er wordt verstuurd.

Poort is al in gebruik

Een ander exemplaar van de server of een ander programma gebruikt de poort nog. Stop dat, of verplaats de server naar een vrije poort. De standaardwaarden van de demo zijn 5416 en 5418.

TLS mislukt op Linux of mobiel

Een wss://-verbinding heeft een werkende TLS-backend nodig. Kies er een via TLSOptions.IOHandler: OpenSSL overal, SChannel op Windows zonder DLL's om mee te leveren, of de native Apple- en Android-handlers in de Enterprise-editie.

Waar mensen naartoe gaan na het eerste bericht

Het chatpaar is de basis. Dit zijn de vier richtingen die het werk meestal op gaat en alle vier zitten in dezelfde bibliotheek.

Spreek een echt protocol

Dezelfde client draagt de subprotocolcomponenten voor MQTT, AMQP, STOMP, Kafka en WAMP. Plaats er een, wijs met de eigenschap Client naar je TsgcWebSocketClient en je zit op een broker.

sgcMQ-snelstart en het protocollenoverzicht

Serveer HTTP naast WebSockets

TsgcWebSocketHTTPServer beantwoordt gewone HTTP-verzoeken en WebSocket-upgrades op dezelfde poort. Dat is wat je wilt als de browser eerst een pagina moet ophalen voordat die een socket opent.

HTTP-componenten

Schaal voorbij één proces

De Enterprise-editie voegt clustering, een load balancer-server en een proxyserver toe, zodat één logisch eindpunt voor meerdere serverprocessen kan staan.

Clusterreferentie en load balancer-referentie

Beveilig het voordat het live gaat

Rate limiting, een circuit breaker, een API-sleutelbeheerder en een firewallcomponent koppel je allemaal aan de server die je al hebt.

Rate limiter, circuit breaker en firewall

Referentie, demo's en documentatie

De referentiepagina's documenteren elke eigenschap en gebeurtenis. De demoprojecten zitten in je download, onder Demos\01.WebSocket_Quick_Start.

Referentie, WebSocket-client Elke eigenschap, methode en gebeurtenis van TsgcWebSocketClient.
Referentie, WebSocket-server Bindings, authenticatie, broadcasting en verbindingsbeheer van TsgcWebSocketServer.
Online help, TsgcWebSocketClient De gegenereerde componentreferentie, altijd in lijn met de huidige release.
Welke editie heb ik nodig Functie voor functie: wat Standard, Professional, Enterprise en All-Access elk inschakelen.
Download de proefversie Hetzelfde installatieprogramma als de productieversie, beperkt in tijd, één per IDE-versie.
Gebruikershandleiding (PDF) De volledige handleiding met alle componenten in de bibliotheek.

Verder lezen: wat WebSockets precies zijn, de connect- en watchdog-gebeurtenissen van de client en het beveiligen van een WebSocket-server. Elk product heeft zijn eigen snelstart, te vinden op de pagina Aan de slag.

Vragen over de sgcWebSockets-snelstart

sgcWebSocket geeft je TsgcWebSocketClient en TsgcWebSocketServer. Voeg ook sgcWebSocket_Classes toe, want elke gebeurtenis geeft je een TsgcWSConnection en dat type wordt daar gedeclareerd. De meegeleverde demo's schrijven uses sgcWebSocket, sgcWebSocket_Classes; en de serverdemo voegt sgcWebSocket_Server toe.
De serverklasse wordt gecompileerd binnen {$IFDEF SGC_EDT_PRO} en de palettregistratie in sgcWebSocket_Reg.pas staat binnen dezelfde beveiliging. SGC_EDT_PRO schakelt het Professional-functieblok in, regel 727 tot 758 van sgcVer.inc. Een Standard-build compileert alleen de client. De clientdefine SGC_WS_CLIENT staat op regel 697 binnen het Standard-blok, regel 675 tot 724.
Ze komen uit sgcWebSocket_Classes.pas. OnConnect is procedure(Connection: TsgcWSConnection). OnDisconnect is procedure(Connection: TsgcWSConnection; Code: Integer). OnMessage is procedure(Connection: TsgcWSConnection; const Text: string). OnError is procedure(Connection: TsgcWSConnection; const Error: string). OnException is procedure(Connection: TsgcWSConnection; E: Exception). Laat de IDE ze genereren in plaats van ze te typen, want een extra of ontbrekende parameter is de meest voorkomende compilerfout in een eerste project.
Ja. sgcWebSocket.pas, sgcWebSocket_Client.pas en sgcWebSocket_Server.pas hebben geen platformbeveiliging op unitniveau en beide componenten zijn geregistreerd met ComponentPlatforms(0), dus de IDE beperkt ze niet tot een doelplatform. Een FireMonkey-client- en serverdemo zit onder Demos\01.WebSocket_Quick_Start\07.Firemonkey_Server_and_Client. Het enige platformbeperkte WebSocket-component in de bibliotheek is TsgcWebSocketClient_WinHTTP, dat voor Win32 en Win64 is.
Stel TLS := True in op de client en laat Port naar de TLS-poort wijzen. Kies daarna een TLS-backend met TLSOptions.IOHandler. OpenSSL werkt overal en heeft op Windows libcrypto-3.dll en libssl-3.dll naast het uitvoerbare bestand nodig. SChannel werkt alleen op Windows en levert niets extra mee. De native Apple- en Android-handlers zijn Enterprise-functies.
Ja, en het derde tabblad hierboven doet precies dat. Wijs de event handlers toe voordat je Active := True instelt, anders kan de eerste OnConnect worden aangeroepen voordat je handler is gekoppeld. Houd er in een consoletoepassing rekening mee dat de client in een eigen thread draait, dus de hoofdthread moet in leven blijven. Daarom eindigt het voorbeeld met Readln.
Het verbindt een weggevallen client opnieuw, met een interval dat je zelf kiest. Schakel het in voor alles wat lang draait, want een netwerkstoring die de socket sluit, laat je toepassing anders stil losgekoppeld achter. Stel WatchDog.Enabled := True in en, als de standaardwaarde te fanatiek is, ook WatchDog.Interval en WatchDog.Attempts.
In je download, onder Demos\. Het paar dat op deze pagina wordt gebruikt, is 01.WebSocket_Quick_Start\01.Server_and_Client_Chat. Ook de moeite waard om vroeg te openen: 06.Authentication voor een server die inloggegevens controleert, 07.Firemonkey_Server_and_Client voor een cross-platform client en 12.Groups voor broadcasten naar een deel van de verbindingen.
De beste deal: All-AccessElk eSeGeCe-product, inclusief Premium-ondersteuning, vanaf €1,059 per jaar.
Bekijk de All-Access-prijzen

Klaar om ermee te bouwen?

Download de proefversie en draai de chatdemo voordat je zelf een regel schrijft.