sgcWebSockets en cinq minutes

Tu as installé la bibliothèque et la palette s'affiche. Cette page t'emmène de là jusqu'à un serveur qui accepte une connexion et un client qui envoie un message et lit la réponse. Tout ce qui suit provient d'une démo livrée dans le téléchargement, tu peux donc ouvrir le projet au lieu de tout taper.

Delphi 7 à RAD Studio 13
Windows, Linux, macOS, iOS, Android
Client à partir de Standard, serveur à partir de Professional
En un coup d'œil

Ce dont a besoin le premier exemple

Deux composants non visuels, une unité dans la clause uses, et une unité supplémentaire pour les types des paramètres des gestionnaires d'événements.

Composant client

TsgcWebSocketClient, déclaré dans sgcWebSocket.pas et enregistré sur la page de palette SGC WebSockets. Renseigne Host, Port, puis Active.

Composant serveur

TsgcWebSocketServer, même unité, même page de palette. Renseigne Port, puis Active. Il écoute, met à niveau la poignée de main et déclenche OnConnect.

La seconde unité

Chaque événement te transmet un TsgcWSConnection, qui se trouve dans sgcWebSocket_Classes.pas. Les démos écrivent uses sgcWebSocket, sgcWebSocket_Classes; et tu devrais faire de même.

Plateformes

Aucune des deux unités ne comporte de garde de plateforme, et les deux composants sont enregistrés avec ComponentPlatforms(0), donc les cibles VCL, FMX, console et service compilent toutes. Une démo de client FireMonkey est fournie dans le téléchargement.

Avant de commencer

Prérequis et éditions

La colonne d'édition indique le define qui conditionne réellement le code, avec la ligne où il se trouve dans Source/sgcVer.inc.

Quoi Valeur
IDE Delphi 7 jusqu'à RAD Studio 13, et C++Builder 2007 jusqu'à 13. Un groupe de packages par version d'IDE sous Packages\.
Clause uses sgcWebSocket pour les composants, sgcWebSocket_Classes pour TsgcWSConnection.
Édition client TsgcWebSocketClient est entouré de {$IFDEF SGC_WS_CLIENT}. SGC_WS_CLIENT est défini à la ligne 697, dans le bloc {$IFDEF SGC_EDT_STD} qui va de la ligne 675 à la ligne 724. Donc Standard et supérieures.
Édition serveur TsgcWebSocketServer est directement entouré de {$IFDEF SGC_EDT_PRO}, et son enregistrement dans la palette, dans sgcWebSocket_Reg.pas, se trouve dans la même garde. Le bloc de fonctionnalités Professional va de la ligne 727 à la ligne 758. Donc Professional et supérieures. Une licence Standard te donne le client, pas le serveur.
Page de palette Enregistrée sous {$IFDEF SGC_PACK_WEBSOCKETS}, défini à la ligne 852.
Plateformes Aucune garde de plateforme au niveau de l'unité dans sgcWebSocket.pas, sgcWebSocket_Client.pas ou sgcWebSocket_Server.pas. Sous Windows, l'unité Windows est incluse de façon conditionnelle, rien de plus.

Tu ne sais pas quelle édition tu utilises ? Ouvre Source/sgcVer.inc et regarde les cinq premières lignes. Les defines SGC_EDT_* y sont cumulatifs : All-Access les définit tous et Standard ne définit que les deux premiers.

Étape 1

Installer et vérifier la palette

Cinq étapes pour passer du zip à un composant que tu peux déposer. Compile le package d'exécution avant d'installer celui de conception, car le second référence le premier.

1. Décompresser

Décompresse le téléchargement dans le dossier de ton choix. Le reste de cette page l'appelle {$DIR}. Les dossiers Source\, Packages\, Demos\ et lib*\ se trouvent tous dessous.

2. Chemin de bibliothèque

Outils, Options, Bibliothèque. Ajoute {$DIR}\source et le dossier correspondant à ton IDE, par exemple {$DIR}\libD13\$(Platform) sur RAD Studio 13 ou {$DIR}\libD12\$(Platform) sur la 12.

3. Compiler les packages

Ouvre {$DIR}\Packages\sgcWebSocketsD13.groupproj pour ta version d'IDE. Compile d'abord sgcWebSocketsD13.dpk, puis installe dclsgcWebSocketsD13.dpk. C++Builder utilise les fichiers .cbproj du même dossier.

4. Vérifier la palette

Une nouvelle page nommée SGC WebSockets apparaît. Dans une version Standard, elle contient TsgcWebSocketClient. À partir de Professional, elle contient aussi TsgcWebSocketServer, TsgcWebSocketHTTPServer, TsgcWebSocketProxyServer et TsgcWebSocketLoadBalancerServer.

5. Ouvrir une démo

Avant d'écrire quoi que ce soit, ouvre {$DIR}\Demos\01.WebSocket_Quick_Start\01.Server_and_Client_Chat. C'est la plus petite paire fonctionnelle de la bibliothèque et le code ci-dessous en provient.

QuickStart

Un serveur et un client, en une vingtaine de lignes

Démarre le serveur, démarre le client, envoie une chaîne. L'onglet serveur écoute sur un port ; l'onglet client s'y connecte et écrit un message.

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;

Dépose TsgcWebSocketServer sur la fiche, nomme-le WSServer, et laisse l'IDE générer les quatre gestionnaires depuis l'Inspecteur d'objets. Connection.IP et Connection.WriteData viennent tous deux de TsgcWSConnection, c'est pourquoi sgcWebSocket_Classes figure dans la clause uses.

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;

Lance d'abord le projet serveur, puis celui-ci. #connected apparaît dans le journal du client et echo: Hello from Delphi revient sur OnMessage. Cet aller-retour constitue tout le démarrage rapide.

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.

Le client exécute son propre thread, donc un programme console doit maintenir le thread principal en vie. C'est à cela que sert le Readln.

Les onglets serveur et client correspondent à la démo livrée Demos\01.WebSocket_Quick_Start\01.Server_and_Client_Chat, dont on a retiré la logique des cases à cocher et des champs de saisie. Le troisième onglet reprend les mêmes appels, écrits avec des composants créés à l'exécution plutôt que déposés sur une fiche.

Étape 2

Prouver l'aller-retour

Quatre événements te disent tout sur le premier lancement, et tu veux les avoir tous les quatre branchés avant d'aller plus loin.

Active

Sur le serveur, Active := True réussit ou lève une exception. Si le port est pris, tu le découvres ici plutôt que trois étapes plus tard.

OnConnect

procedure(Connection: TsgcWSConnection). Se déclenche des deux côtés. Sur le serveur, Connection.IP t'indique qui est arrivé ; sur le client, c'est la preuve que la poignée de main a été mise à niveau.

OnMessage

procedure(Connection: TsgcWSConnection; const Text: string). L'écho qui revient sur le client prouve l'aller-retour de bout en bout.

OnError et OnException

procedure(Connection: TsgcWSConnection; const Error: string) et procedure(Connection: TsgcWSConnection; E: Exception). Branche les deux. Sans eux, un échec est silencieux et donne l'impression que rien ne s'est passé.

Problèmes courants

Ce qui se passe généralement mal la première fois

Presque tous les problèmes du premier lancement sont l'un de ces six.

TsgcWebSocketServer n'est pas dans la palette

La classe serveur n'est compilée que lorsque SGC_EDT_PRO est défini, à la ligne 130 de sgcWebSocket.pas, et n'est enregistrée que dans la même garde. Dans une version Standard, le client est présent et le serveur non. C'est une question de licence, pas une installation cassée.

Identifiant non déclaré TsgcWSConnection

Les composants se trouvent dans sgcWebSocket, l'objet de connexion dans sgcWebSocket_Classes. Ajoute la seconde unité à la clause uses. Chaque démo livrée contient les deux.

Le client se connecte, puis se déconnecte

Définis WatchDog.Enabled := True pour qu'une connexion perdue se rétablisse d'elle-même, et gère OnError et OnException. Une déconnexion silencieuse sans gestionnaire donne l'impression que rien ne s'est passé.

Rien n'arrive au serveur

Vérifie que le client est vraiment connecté avant d'écrire. WriteData sur un client inactif ne fait rien d'utile, c'est pourquoi la démo teste if WSClient.Active then avant d'envoyer.

Port déjà utilisé

Une autre instance du serveur, ou un autre programme, occupe toujours le port. Arrête-la, ou déplace le serveur vers un port libre. Les valeurs par défaut de la démo sont 5416 et 5418.

Échec de TLS sous Linux ou sur mobile

Une connexion wss:// nécessite un moteur TLS fonctionnel. Choisis-en un via TLSOptions.IOHandler : OpenSSL partout, SChannel sous Windows sans DLL à déployer, ou les gestionnaires natifs Apple et Android dans l'édition Enterprise.

Aller plus loin

Où vont les gens après le premier message

La paire de chat n'est que le point de départ. Voici les quatre directions que prend généralement le travail, et les quatre se trouvent dans la même bibliothèque.

Parler un vrai protocole

Le même client transporte les composants de sous-protocole MQTT, AMQP, STOMP, Kafka et WAMP. Dépose-en un, pointe sa propriété Client vers ton TsgcWebSocketClient, et tu es sur un broker.

Démarrage rapide de sgcMQ et l'aperçu des protocoles

Servir du HTTP en plus des WebSockets

TsgcWebSocketHTTPServer répond aux requêtes HTTP ordinaires et aux mises à niveau WebSocket sur le même port, ce qu'il te faut quand le navigateur doit récupérer une page avant d'ouvrir un socket.

Composants HTTP

Passer à l'échelle au-delà d'un processus

L'édition Enterprise ajoute le clustering, un serveur d'équilibrage de charge et un serveur proxy, de sorte qu'un seul point d'accès logique peut se placer devant plusieurs processus serveur.

Référence du cluster et référence de l'équilibreur de charge

Le durcir avant la livraison

La limitation de débit, un circuit breaker, un gestionnaire de clés API et un composant firewall se rattachent tous au serveur que tu as déjà.

Rate limiter, circuit breaker et firewall

Ressources

Référence, démos et documentation

Les pages de référence documentent chaque propriété et chaque événement. Les projets de démo sont dans ton téléchargement, sous Demos\01.WebSocket_Quick_Start.

Référence, client WebSocket Chaque propriété, méthode et événement de TsgcWebSocketClient. Ouvrir
Référence, serveur WebSocket Liaisons, authentification, diffusion et gestion des connexions sur TsgcWebSocketServer. Ouvrir
Aide en ligne, TsgcWebSocketClient La référence générée du composant, toujours en phase avec la version actuelle. Ouvrir
De quelle édition ai-je besoin Fonctionnalité par fonctionnalité, ce que chacune des éditions Standard, Professional, Enterprise et All-Access active. Ouvrir
Télécharger l'essai Le même installeur que la version de production, limité dans le temps, un par version d'IDE. Ouvrir
Manuel utilisateur (PDF) Le manuel complet couvrant tous les composants de la bibliothèque. Ouvrir

Lectures associées : ce que sont réellement les WebSockets, les événements de connexion et de watchdog du client, et sécuriser un serveur WebSocket. Chaque produit a son propre démarrage rapide, listé sur la page de prise en main.

FAQ

Questions sur le démarrage rapide de sgcWebSockets

sgcWebSocket te donne TsgcWebSocketClient et TsgcWebSocketServer. Ajoute aussi sgcWebSocket_Classes, car chaque événement te transmet un TsgcWSConnection et ce type y est déclaré. Les démos livrées écrivent uses sgcWebSocket, sgcWebSocket_Classes; et la démo serveur ajoute sgcWebSocket_Server.
La classe serveur est compilée dans {$IFDEF SGC_EDT_PRO}, et son enregistrement dans la palette, dans sgcWebSocket_Reg.pas, se trouve dans la même garde. SGC_EDT_PRO active le bloc de fonctionnalités Professional, lignes 727 à 758 de sgcVer.inc. Une version Standard ne compile que le client. Le define du client, SGC_WS_CLIENT, est à la ligne 697 dans le bloc Standard, lignes 675 à 724.
Elles viennent de sgcWebSocket_Classes.pas. OnConnect est procedure(Connection: TsgcWSConnection). OnDisconnect est procedure(Connection: TsgcWSConnection; Code: Integer). OnMessage est procedure(Connection: TsgcWSConnection; const Text: string). OnError est procedure(Connection: TsgcWSConnection; const Error: string). OnException est procedure(Connection: TsgcWSConnection; E: Exception). Laisse l'IDE les générer plutôt que de les taper, car un paramètre en trop ou manquant est l'erreur de compilation la plus courante sur un premier projet.
Oui. sgcWebSocket.pas, sgcWebSocket_Client.pas et sgcWebSocket_Server.pas ne comportent aucune garde de plateforme au niveau de l'unité, et les deux composants sont enregistrés avec ComponentPlatforms(0), donc l'IDE ne les restreint pas à une cible. Une démo de client et serveur FireMonkey est fournie sous Demos\01.WebSocket_Quick_Start\07.Firemonkey_Server_and_Client. Le seul composant WebSocket restreint à une plateforme dans la bibliothèque est TsgcWebSocketClient_WinHTTP, qui est Win32 et Win64.
Définis TLS := True sur le client et pointe Port vers le port TLS. Choisis ensuite un moteur TLS avec TLSOptions.IOHandler. OpenSSL fonctionne partout et nécessite libcrypto-3.dll et libssl-3.dll à côté de l'exécutable sous Windows. SChannel est réservé à Windows et ne livre rien de plus. Les gestionnaires natifs Apple et Android sont des fonctionnalités Enterprise.
Oui, et le troisième onglet ci-dessus fait exactement cela. Affecte les gestionnaires d'événements avant de définir Active := True, sinon le premier OnConnect peut se déclencher avant que ton gestionnaire soit attaché. Dans une application console, rappelle-toi que le client exécute son propre thread, donc le thread principal doit rester en vie, c'est pourquoi l'exemple se termine par Readln.
Il reconnecte un client qui s'est déconnecté, selon un intervalle que tu choisis. Active-le pour toute application de longue durée, car une coupure réseau qui ferme le socket laissera sinon ton application déconnectée en silence. Définis WatchDog.Enabled := True et, si la valeur par défaut est trop insistante, WatchDog.Interval et WatchDog.Attempts.
Dans ton téléchargement, sous Demos\. La paire utilisée sur cette page est 01.WebSocket_Quick_Start\01.Server_and_Client_Chat. Utile aussi à ouvrir tôt : 06.Authentication pour un serveur qui vérifie les identifiants, 07.Firemonkey_Server_and_Client pour un client multiplateforme, et 12.Groups pour diffuser vers un sous-ensemble de connexions.
Meilleur rapport qualité-prix : All-AccessTous les produits eSeGeCe, Support Premium inclus, à partir de €1,059/an.
Voir les tarifs All-Access

Prêt à construire dessus ?

Télécharge l'essai et lance la démo de chat avant d'écrire une seule ligne à toi.

Télécharger l'essai gratuit Voir les tarifs