sgcWebSockets w pięć minut

Biblioteka jest już zainstalowana i paleta komponentów jest widoczna. Ta strona prowadzi cię stąd do serwera, który przyjmuje połączenie, oraz klienta, który wysyła wiadomość i odczytuje odpowiedź. Wszystko poniżej pochodzi z dema dołączonego do pobranego pakietu, więc możesz otworzyć projekt zamiast przepisywać kod.

Delphi 7 do RAD Studio 13
Windows, Linux, macOS, iOS, Android
Klient od edycji Standard, serwer od Professional
W skrócie

Czego potrzebuje pierwszy przykład

Dwa komponenty niewizualne, jedna jednostka w klauzuli uses i jedna dodatkowa jednostka dla typów parametrów obsługi zdarzeń.

Komponent klienta

TsgcWebSocketClient, zadeklarowany w sgcWebSocket.pas i zarejestrowany na stronie palety SGC WebSockets. Ustaw Host, Port, a następnie Active.

Komponent serwera

TsgcWebSocketServer, ta sama jednostka, ta sama strona palety. Ustaw Port, a następnie Active. Nasłuchuje, uaktualnia uzgadnianie połączenia i wywołuje OnConnect.

Druga jednostka

Każde zdarzenie przekazuje ci obiekt TsgcWSConnection, który znajduje się w sgcWebSocket_Classes.pas. Dema zawierają uses sgcWebSocket, sgcWebSocket_Classes; i ty też powinieneś to dodać.

Platformy

Żadna z tych jednostek nie zawiera warunku platformy, a oba komponenty są zarejestrowane z ComponentPlatforms(0), więc kompilują się cele VCL, FMX, konsolowe i usługowe. W pakiecie znajduje się demo klienta FireMonkey.

Zanim zaczniesz

Wymagania i edycje

Kolumna edycji to define, który faktycznie ogranicza kod, wraz z linią w Source/sgcVer.inc, w której się znajduje.

Co Wartość
IDE Od Delphi 7 do RAD Studio 13 oraz od C++Builder 2007 do 13. Jedna grupa pakietów dla każdej wersji IDE w katalogu Packages\.
Klauzula uses sgcWebSocket dla komponentów, sgcWebSocket_Classes dla TsgcWSConnection.
Edycja klienta TsgcWebSocketClient jest objęty {$IFDEF SGC_WS_CLIENT}. SGC_WS_CLIENT jest zdefiniowany w linii 697, wewnątrz bloku {$IFDEF SGC_EDT_STD}, który biegnie od linii 675 do linii 724. Czyli Standard i wyższe.
Edycja serwera TsgcWebSocketServer jest objęty bezpośrednio {$IFDEF SGC_EDT_PRO}, a jego rejestracja na palecie w sgcWebSocket_Reg.pas znajduje się w tym samym warunku. Blok funkcji Professional biegnie od linii 727 do linii 758. Czyli Professional i wyższe. Licencja Standard daje klienta, ale nie serwer.
Strona palety Zarejestrowana w {$IFDEF SGC_PACK_WEBSOCKETS}, zdefiniowanym w linii 852.
Platformy Brak warunku platformy na poziomie jednostki w sgcWebSocket.pas, sgcWebSocket_Client.pas ani sgcWebSocket_Server.pas. W systemie Windows warunkowo dołączana jest jednostka Windows, nic więcej.

Nie wiesz, której edycji używasz? Otwórz Source/sgcVer.inc i spójrz na pierwszych pięć linii. Definy SGC_EDT_* są tam kumulatywne, więc All-Access definiuje wszystkie, a Standard tylko pierwsze dwa.

Krok 1

Zainstaluj i sprawdź paletę

Pięć kroków od pliku zip do komponentu, który możesz upuścić na formularz. Skompiluj pakiet uruchomieniowy przed zainstalowaniem pakietu czasu projektowania, ponieważ ten drugi odwołuje się do pierwszego.

1. Rozpakuj

Rozpakuj pobrany plik do wybranego folderu. Dalej na tej stronie nazywamy go {$DIR}. Foldery Source\, Packages\, Demos\ i lib*\ znajdują się w nim wszystkie.

2. Ścieżka biblioteki

Tools, Options, Library. Dodaj {$DIR}\source oraz folder odpowiadający twojemu IDE, na przykład {$DIR}\libD13\$(Platform) w RAD Studio 13 lub {$DIR}\libD12\$(Platform) w wersji 12.

3. Zbuduj pakiety

Otwórz {$DIR}\Packages\sgcWebSocketsD13.groupproj dla swojej wersji IDE. Najpierw skompiluj sgcWebSocketsD13.dpk, a następnie zainstaluj dclsgcWebSocketsD13.dpk. C++Builder używa plików .cbproj z tego samego folderu.

4. Sprawdź paletę

Pojawia się nowa strona o nazwie SGC WebSockets. W kompilacji Standard zawiera TsgcWebSocketClient. W Professional i wyższych zawiera także TsgcWebSocketServer, TsgcWebSocketHTTPServer, TsgcWebSocketProxyServer i TsgcWebSocketLoadBalancerServer.

5. Otwórz demo

Zanim cokolwiek napiszesz, otwórz {$DIR}\Demos\01.WebSocket_Quick_Start\01.Server_and_Client_Chat. To najmniejsza działająca para w bibliotece i kod poniżej pochodzi właśnie stamtąd.

QuickStart

Serwer i klient w około dwudziestu linijkach

Uruchom serwer, uruchom klienta, wyślij ciąg znaków. Karta serwera nasłuchuje na porcie, a karta klienta łączy się z nim i zapisuje jedną wiadomość.

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;

Upuść TsgcWebSocketServer na formularz, nazwij go WSServer i pozwól IDE wygenerować cztery procedury obsługi z Object Inspectora. Connection.IP i Connection.WriteData pochodzą z TsgcWSConnection, dlatego sgcWebSocket_Classes znajduje się w klauzuli 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;

Najpierw uruchom projekt serwera, potem ten. W logu klienta pojawia się #connected, a w OnMessage wraca echo: Hello from Delphi. Ta wymiana to cały szybki start.

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.

Klient działa we własnym wątku, więc program konsolowy musi utrzymać przy życiu wątek główny. Do tego służy Readln.

Karty serwera i klienta to dostarczane demo Demos\01.WebSocket_Quick_Start\01.Server_and_Client_Chat, z usuniętą obsługą pól wyboru i pól edycji z dema. Trzecia karta zawiera te same wywołania zapisane dla komponentów tworzonych w czasie działania zamiast upuszczanych na formularz.

Krok 2

Potwierdź wymianę w obie strony

Cztery zdarzenia mówią ci wszystko o pierwszym uruchomieniu i chcesz mieć podpięte wszystkie cztery, zanim pójdziesz dalej.

Active

Na serwerze Active := True albo się powiedzie, albo zgłosi wyjątek. Jeśli port jest zajęty, dowiesz się o tym tutaj, a nie trzy kroki później.

OnConnect

procedure(Connection: TsgcWSConnection). Wywoływane po obu stronach. Na serwerze Connection.IP mówi, kto się połączył; u klienta jest dowodem, że uzgadnianie zostało uaktualnione.

OnMessage

procedure(Connection: TsgcWSConnection; const Text: string). Echo wracające do klienta to potwierdzenie wymiany w obie strony od początku do końca.

OnError i OnException

procedure(Connection: TsgcWSConnection; const Error: string) oraz procedure(Connection: TsgcWSConnection; E: Exception). Podepnij oba. Bez nich awaria jest cicha i wygląda tak, jakby nic się nie stało.

Typowe problemy

Co zwykle idzie nie tak za pierwszym razem

Prawie każdy problem przy pierwszym uruchomieniu to jeden z tych sześciu.

TsgcWebSocketServer nie ma na palecie

Klasa serwera jest kompilowana tylko wtedy, gdy zdefiniowano SGC_EDT_PRO, w linii 130 pliku sgcWebSocket.pas, i rejestrowana tylko wewnątrz tego samego warunku. W kompilacji Standard klient jest, a serwera nie ma. To kwestia licencji, a nie uszkodzonej instalacji.

Niezadeklarowany identyfikator TsgcWSConnection

Komponenty znajdują się w sgcWebSocket, a obiekt połączenia w sgcWebSocket_Classes. Dodaj drugą jednostkę do klauzuli uses. Każde dostarczane demo ma obie.

Klient łączy się, a potem się rozłącza

Ustaw WatchDog.Enabled := True, aby zerwane połączenie było nawiązywane ponownie samo, i obsłuż OnError oraz OnException. Ciche rozłączenie bez procedury obsługi wygląda tak, jakby nic się nie stało.

Do serwera nic nie dociera

Sprawdź, czy klient naprawdę działa, zanim zaczniesz zapisywać. WriteData na nieaktywnym kliencie nie robi nic pożytecznego, dlatego demo sprawdza if WSClient.Active then przed wysłaniem.

Port jest już używany

Inna instancja serwera albo inny program nadal zajmuje port. Zatrzymaj go lub przenieś serwer na wolny port. Domyślne porty w demach to 5416 i 5418.

TLS nie działa w Linuksie lub na urządzeniach mobilnych

Połączenie wss:// wymaga działającego zaplecza TLS. Wybierz je przez TLSOptions.IOHandler: OpenSSL wszędzie, SChannel w systemie Windows bez bibliotek DLL do wdrożenia lub natywne handlery Apple i Android w edycji Enterprise.

Zgłęb temat

Dokąd ludzie idą po pierwszej wiadomości

Para czatu to fundament. To cztery kierunki, w które zwykle idzie praca, a wszystkie cztery są w tej samej bibliotece.

Używaj prawdziwego protokołu

Ten sam klient obsługuje komponenty podprotokołów MQTT, AMQP, STOMP, Kafka i WAMP. Upuść jeden, wskaż jego właściwość Client na swój TsgcWebSocketClient i jesteś połączony z brokerem.

Szybki start sgcMQ oraz przegląd protokołów

Obsługuj HTTP obok WebSocketów

TsgcWebSocketHTTPServer odpowiada na zwykłe żądania HTTP i uaktualnienia do WebSocket na tym samym porcie, co jest potrzebne, gdy przeglądarka musi pobrać stronę, zanim otworzy gniazdo.

Komponenty HTTP

Skaluj ponad jeden proces

Edycja Enterprise dodaje klastrowanie, serwer równoważenia obciążenia i serwer proxy, dzięki czemu jeden logiczny punkt końcowy może stać przed kilkoma procesami serwera.

Dokumentacja klastra i dokumentacja load balancera

Utwardź go przed wydaniem

Ograniczanie liczby żądań, circuit breaker, menedżer kluczy API i komponent firewall podłączają się do serwera, który już masz.

Rate limiter, circuit breaker i firewall

Zasoby

Dokumentacja, dema i materiały

Strony referencyjne opisują każdą właściwość i zdarzenie. Projekty demo znajdują się w pobranym pakiecie, w Demos\01.WebSocket_Quick_Start.

Dokumentacja, klient WebSocket Każda właściwość, metoda i zdarzenie TsgcWebSocketClient. Otwórz
Dokumentacja, serwer WebSocket Powiązania, uwierzytelnianie, rozgłaszanie i zarządzanie połączeniami w TsgcWebSocketServer. Otwórz
Pomoc online, TsgcWebSocketClient Generowana dokumentacja komponentu, zawsze zgodna z bieżącym wydaniem. Otwórz
Której edycji potrzebuję Funkcja po funkcji, co włączają Standard, Professional, Enterprise i All-Access. Otwórz
Pobierz wersję próbną Ten sam instalator co w wersji produkcyjnej, z ograniczeniem czasowym, jedna dla każdej wersji IDE. Otwórz
Podręcznik użytkownika (PDF) Pełny podręcznik obejmujący każdy komponent biblioteki. Otwórz

Powiązane lektury: czym naprawdę są WebSockety, zdarzenia połączenia i watchdoga klienta oraz zabezpieczanie serwera WebSocket. Każdy produkt ma własny szybki start, wymieniony na stronie pierwszych kroków.

FAQ

Pytania o szybki start sgcWebSockets

sgcWebSocket daje ci TsgcWebSocketClient i TsgcWebSocketServer. Dodaj także sgcWebSocket_Classes, ponieważ każde zdarzenie przekazuje TsgcWSConnection, a ten typ jest zadeklarowany właśnie tam. Dostarczane dema zawierają uses sgcWebSocket, sgcWebSocket_Classes;, a demo serwera dodaje sgcWebSocket_Server.
Klasa serwera jest kompilowana wewnątrz {$IFDEF SGC_EDT_PRO}, a jej rejestracja na palecie w sgcWebSocket_Reg.pas znajduje się w tym samym warunku. SGC_EDT_PRO włącza blok funkcji Professional, linie 727 do 758 pliku sgcVer.inc. Kompilacja Standard zawiera tylko klienta. Define klienta, SGC_WS_CLIENT, znajduje się w linii 697 wewnątrz bloku Standard, linie 675 do 724.
Pochodzą z sgcWebSocket_Classes.pas. OnConnect to procedure(Connection: TsgcWSConnection). OnDisconnect to procedure(Connection: TsgcWSConnection; Code: Integer). OnMessage to procedure(Connection: TsgcWSConnection; const Text: string). OnError to procedure(Connection: TsgcWSConnection; const Error: string). OnException to procedure(Connection: TsgcWSConnection; E: Exception). Pozwól IDE je wygenerować zamiast wpisywać je ręcznie, ponieważ dodatkowy lub brakujący parametr to najczęstszy błąd kompilacji w pierwszym projekcie.
Tak. sgcWebSocket.pas, sgcWebSocket_Client.pas i sgcWebSocket_Server.pas nie mają warunku platformy na poziomie jednostki, a oba komponenty są zarejestrowane z ComponentPlatforms(0), więc IDE nie ogranicza ich do jednego celu. Demo klienta i serwera FireMonkey znajduje się w Demos\01.WebSocket_Quick_Start\07.Firemonkey_Server_and_Client. Jedynym komponentem WebSocket w bibliotece ograniczonym do platformy jest TsgcWebSocketClient_WinHTTP, dostępny w Win32 i Win64.
Ustaw TLS := True w kliencie i wskaż w Port port TLS. Następnie wybierz zaplecze TLS przez TLSOptions.IOHandler. OpenSSL działa wszędzie i w systemie Windows wymaga libcrypto-3.dll oraz libssl-3.dll obok pliku wykonywalnego. SChannel działa tylko w systemie Windows i nie wymaga niczego dodatkowego. Natywne handlery Apple i Android to funkcje edycji Enterprise.
Tak, i dokładnie to robi trzecia karta powyżej. Przypisz procedury obsługi zdarzeń przed ustawieniem Active := True, w przeciwnym razie pierwsze OnConnect może wystąpić, zanim twoja procedura zostanie podpięta. W aplikacji konsolowej pamiętaj, że klient działa we własnym wątku, więc wątek główny musi pozostać przy życiu, dlatego przykład kończy się Readln.
Ponownie łączy klienta, który się rozłączył, w wybranym przez ciebie odstępie czasu. Włącz go w każdej długo działającej aplikacji, ponieważ chwilowa awaria sieci zamykająca gniazdo w przeciwnym razie zostawi aplikację po cichu rozłączoną. Ustaw WatchDog.Enabled := True i, jeśli domyślne wartości są zbyt gorliwe, WatchDog.Interval oraz WatchDog.Attempts.
W pobranym pakiecie, w Demos\. Para użyta na tej stronie to 01.WebSocket_Quick_Start\01.Server_and_Client_Chat. Warto też otworzyć wcześnie: 06.Authentication dla serwera sprawdzającego poświadczenia, 07.Firemonkey_Server_and_Client dla klienta wieloplatformowego oraz 12.Groups dla rozgłaszania do podzbioru połączeń.
Najkorzystniejsza oferta: All-AccessWszystkie produkty eSeGeCe, ze wsparciem Premium w cenie, już od €1,059 rocznie.
Zobacz cennik All-Access

Gotowy, by na tym budować?

Pobierz wersję próbną i uruchom demo czatu, zanim napiszesz własną linijkę kodu.

Pobierz bezpłatną wersję próbną Zobacz cennik