라이브러리를 설치했고 팔레트도 보이는 상태예요. 이 페이지는 거기서부터 연결을 받아 주는 서버, 그리고 메시지를 보내고 응답을 읽는 클라이언트까지 안내해요. 아래 내용은 모두 다운로드에 포함된 데모에서 가져온 것이니, 직접 입력하는 대신 프로젝트를 열어 보세요.
비주얼이 없는 컴포넌트 두 개, uses 절에 넣을 유닛 하나, 그리고 이벤트 핸들러 매개변수 타입을 위한 유닛 하나가 더 필요해요.
TsgcWebSocketClient는 sgcWebSocket.pas에 선언되어 있고 SGC WebSockets 팔레트 페이지에 등록돼요. Host와 Port를 설정한 다음 Active를 설정하세요.
TsgcWebSocketServer는 같은 유닛, 같은 팔레트 페이지에 있어요. Port를 설정한 다음 Active를 설정하세요. 연결을 기다리고, 핸드셰이크를 업그레이드한 뒤 OnConnect를 발생시켜요.
모든 이벤트는 TsgcWSConnection을 전달하며, 이 타입은 sgcWebSocket_Classes.pas에 있어요. 데모는 uses sgcWebSocket, sgcWebSocket_Classes;라고 작성하니 여러분도 똑같이 쓰세요.
두 유닛 모두 플랫폼 가드가 없고 두 컴포넌트 모두 ComponentPlatforms(0)으로 등록되어 있어서 VCL, FMX, 콘솔, 서비스 대상이 모두 컴파일돼요. FireMonkey 클라이언트 데모도 포함되어 있어요.
에디션 열은 실제로 코드를 제어하는 define이며, Source/sgcVer.inc에서 해당 define이 있는 줄 번호도 함께 적었어요.
| 항목 | 값 |
|---|---|
| IDE | Delphi 7부터 RAD Studio 13까지, 그리고 C++Builder 2007부터 13까지. IDE 버전별 패키지 그룹이 Packages\ 아래에 하나씩 있어요. |
| Uses 절 | 컴포넌트는 sgcWebSocket, TsgcWSConnection은 sgcWebSocket_Classes. |
| 클라이언트 에디션 | TsgcWebSocketClient는 {$IFDEF SGC_WS_CLIENT}로 감싸져 있어요. SGC_WS_CLIENT는 697번째 줄에 정의되어 있으며, 675번째 줄부터 724번째 줄까지 이어지는 {$IFDEF SGC_EDT_STD} 블록 안에 있어요. 따라서 Standard 이상이에요. |
| 서버 에디션 | TsgcWebSocketServer는 {$IFDEF SGC_EDT_PRO}로 직접 감싸져 있고, sgcWebSocket_Reg.pas의 팔레트 등록도 같은 가드 안에 있어요. Professional 기능 블록은 727번째 줄부터 758번째 줄까지예요. 따라서 Professional 이상이에요. Standard 라이선스로는 클라이언트만 쓸 수 있고 서버는 쓸 수 없어요. |
| 팔레트 페이지 | 852번째 줄에 정의된 {$IFDEF SGC_PACK_WEBSOCKETS} 아래에 등록돼요. |
| 플랫폼 | sgcWebSocket.pas, sgcWebSocket_Client.pas, sgcWebSocket_Server.pas에는 유닛 범위의 플랫폼 가드가 없어요. Windows에서는 Windows 유닛을 조건부로 가져올 뿐 그 외에는 아무것도 없어요. |
어떤 에디션을 쓰고 있는지 모르겠다면 Source/sgcVer.inc를 열어 처음 다섯 줄을 확인하세요. 여기의 SGC_EDT_* define은 누적 방식이라 All-Access는 모두 정의하고 Standard는 처음 두 개만 정의해요.
zip 파일에서 드롭할 수 있는 컴포넌트까지 다섯 단계예요. 디자인 타임 패키지는 런타임 패키지를 참조하므로, 런타임 패키지를 먼저 컴파일한 뒤 설치하세요.
다운로드한 파일을 원하는 폴더에 압축 해제하세요. 이 페이지에서는 그 폴더를 {$DIR}이라고 불러요. Source\, Packages\, Demos\, lib*\ 폴더가 모두 그 아래에 있어요.
Tools, Options, Library로 이동해요. {$DIR}\source와 사용하는 IDE에 맞는 폴더를 추가하세요. 예를 들어 RAD Studio 13에서는 {$DIR}\libD13\$(Platform), 12에서는 {$DIR}\libD12\$(Platform)이에요.
IDE 버전에 맞는 {$DIR}\Packages\sgcWebSocketsD13.groupproj를 여세요. sgcWebSocketsD13.dpk를 먼저 컴파일하고 그다음 dclsgcWebSocketsD13.dpk를 설치해요. C++Builder는 같은 폴더의 .cbproj 파일을 사용해요.
SGC WebSockets라는 새 페이지가 나타나요. Standard 빌드에는 TsgcWebSocketClient가 들어 있어요. Professional 이상에는 TsgcWebSocketServer, TsgcWebSocketHTTPServer, TsgcWebSocketProxyServer, TsgcWebSocketLoadBalancerServer도 들어 있어요.
코드를 작성하기 전에 {$DIR}\Demos\01.WebSocket_Quick_Start\01.Server_and_Client_Chat을 열어 보세요. 라이브러리에서 가장 작은 동작 예제이며, 아래 코드도 여기서 가져온 거예요.
서버를 시작하고, 클라이언트를 시작하고, 문자열을 보내요. 서버 탭은 포트에서 연결을 기다리고, 클라이언트 탭은 서버에 연결해 메시지 하나를 써요.
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;폼에 TsgcWebSocketServer를 올리고 이름을 WSServer로 지정한 뒤, Object Inspector에서 IDE가 핸들러 네 개를 생성하도록 하세요. Connection.IP와 Connection.WriteData는 모두 TsgcWSConnection에서 오기 때문에 uses 절에 sgcWebSocket_Classes가 들어가요.
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;서버 프로젝트를 먼저 실행한 다음 이 프로젝트를 실행하세요. 클라이언트 로그에 #connected가 나타나고 OnMessage로 echo: Hello from Delphi가 돌아와요. 이 왕복이 빠른 시작의 전부예요.
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.클라이언트는 자체 스레드에서 실행되므로 콘솔 프로그램은 메인 스레드를 계속 살려 두어야 해요. Readln이 바로 그 역할을 해요.
서버와 클라이언트 탭은 포함된 데모 Demos\01.WebSocket_Quick_Start\01.Server_and_Client_Chat에서 데모의 체크박스와 편집 상자 처리 코드를 뺀 것이에요. 세 번째 탭은 폼에 올리는 대신 런타임에 생성한 컴포넌트에 같은 호출을 작성한 거예요.
이벤트 네 개가 첫 실행에 대한 모든 것을 알려 줘요. 더 나아가기 전에 네 개를 모두 연결해 두세요.
Active서버에서 Active := True는 성공하거나 예외를 발생시켜요. 포트가 이미 사용 중이라면 세 단계 뒤가 아니라 바로 여기서 알 수 있어요.
OnConnectprocedure(Connection: TsgcWSConnection). 양쪽 모두에서 발생해요. 서버에서는 Connection.IP로 누가 접속했는지 알 수 있고, 클라이언트에서는 핸드셰이크가 업그레이드되었다는 증거가 돼요.
OnMessageprocedure(Connection: TsgcWSConnection; const Text: string). 클라이언트에 에코가 돌아오면 종단 간 왕복이 증명된 거예요.
OnError와 OnExceptionprocedure(Connection: TsgcWSConnection; const Error: string)과 procedure(Connection: TsgcWSConnection; E: Exception). 둘 다 연결하세요. 연결하지 않으면 실패해도 아무 소리 없이 지나가서 아무 일도 없었던 것처럼 보여요.
첫 실행 문제는 거의 다 이 여섯 가지 중 하나예요.
TsgcWebSocketServer가 팔레트에 없어요서버 클래스는 sgcWebSocket.pas의 130번째 줄에서 SGC_EDT_PRO가 정의된 경우에만 컴파일되고, 같은 가드 안에서만 등록돼요. Standard 빌드에는 클라이언트만 있고 서버는 없어요. 설치가 잘못된 것이 아니라 라이선스 때문이에요.
TsgcWSConnection컴포넌트는 sgcWebSocket에 있고, 연결 객체는 sgcWebSocket_Classes에 있어요. 두 번째 유닛을 uses 절에 추가하세요. 포함된 모든 데모에는 두 유닛이 다 들어 있어요.
WatchDog.Enabled := True로 설정하면 끊어진 연결을 자동으로 다시 연결해요. 그리고 OnError와 OnException도 처리하세요. 핸들러 없이 조용히 연결이 끊기면 아무 일도 없었던 것처럼 보여요.
쓰기 전에 클라이언트가 실제로 연결되어 있는지 확인하세요. 비활성 클라이언트에서 WriteData를 호출해도 의미 있는 일은 일어나지 않아요. 그래서 데모도 보내기 전에 if WSClient.Active then을 검사해요.
서버의 다른 인스턴스나 다른 프로그램이 아직 그 포트를 점유하고 있어요. 그것을 중지하거나 서버를 비어 있는 포트로 옮기세요. 데모의 기본값은 5416과 5418이에요.
wss:// 연결에는 동작하는 TLS 백엔드가 필요해요. TLSOptions.IOHandler로 선택하세요. OpenSSL은 모든 플랫폼에서, SChannel은 배포할 DLL 없이 Windows에서, Apple과 Android 네이티브 핸들러는 Enterprise 에디션에서 사용할 수 있어요.
채팅 예제는 출발점일 뿐이에요. 작업이 보통 향하는 네 가지 방향이 있고, 모두 같은 라이브러리 안에 있어요.
같은 클라이언트가 MQTT, AMQP, STOMP, Kafka, WAMP 서브 프로토콜 컴포넌트를 실어 나를 수 있어요. 하나를 올리고 Client 속성을 TsgcWebSocketClient로 지정하면 브로커에 연결돼요.
TsgcWebSocketHTTPServer는 같은 포트에서 일반 HTTP 요청과 WebSocket 업그레이드에 모두 응답해요. 브라우저가 소켓을 열기 전에 페이지를 먼저 가져와야 할 때 알맞아요.
Enterprise 에디션은 클러스터링, 로드 밸런서 서버, 프록시 서버를 추가해서 하나의 논리적 엔드포인트가 여러 서버 프로세스 앞에 설 수 있어요.
Rate Limiter, Circuit Breaker, API 키 관리자, 방화벽 컴포넌트는 모두 이미 쓰고 있는 서버에 붙일 수 있어요.
레퍼런스 페이지에는 모든 속성과 이벤트가 문서화되어 있어요. 데모 프로젝트는 다운로드 안의 Demos\01.WebSocket_Quick_Start 아래에 있어요.
레퍼런스, WebSocket 클라이언트
TsgcWebSocketClient의 모든 속성, 메서드, 이벤트.
|
열기 | |
레퍼런스, WebSocket 서버
TsgcWebSocketServer의 바인딩, 인증, 브로드캐스트, 연결 관리.
|
열기 | |
| 온라인 도움말, TsgcWebSocketClient 자동 생성된 컴포넌트 레퍼런스로, 항상 최신 릴리스와 일치해요. | 열기 | |
| 어떤 에디션이 필요한가요 Standard, Professional, Enterprise, All-Access가 각각 어떤 기능을 켜 주는지 기능별로 비교해요. | 열기 | |
| 체험판 다운로드 정식 버전과 같은 설치 프로그램이며, 기간 제한이 있고 IDE 버전별로 하나씩 제공돼요. | 열기 | |
| 사용자 설명서 (PDF) 라이브러리의 모든 컴포넌트를 다루는 전체 설명서. | 열기 |
함께 읽어 보세요. WebSocket이란 무엇인가, 클라이언트 연결 및 WatchDog 이벤트, WebSocket 서버 보안. 모든 제품에는 각자의 빠른 시작이 있으며, 시작하기 페이지에서 모아 볼 수 있어요.
sgcWebSocket이 TsgcWebSocketClient와 TsgcWebSocketServer를 제공해요. 모든 이벤트가 TsgcWSConnection을 전달하고 그 타입이 sgcWebSocket_Classes에 선언되어 있으므로 이 유닛도 추가하세요. 포함된 데모는 uses sgcWebSocket, sgcWebSocket_Classes;라고 작성하고, 서버 데모는 sgcWebSocket_Server를 추가해요.
{$IFDEF SGC_EDT_PRO} 안에서 컴파일되고, sgcWebSocket_Reg.pas의 팔레트 등록도 같은 가드 안에 있어요. SGC_EDT_PRO는 sgcVer.inc의 727번째 줄부터 758번째 줄까지인 Professional 기능 블록을 켜요. Standard 빌드는 클라이언트만 컴파일해요. 클라이언트 define인 SGC_WS_CLIENT는 675번째 줄부터 724번째 줄까지인 Standard 블록 안의 697번째 줄에 있어요.
sgcWebSocket_Classes.pas에서 와요. OnConnect는 procedure(Connection: TsgcWSConnection)이에요. OnDisconnect는 procedure(Connection: TsgcWSConnection; Code: Integer)이에요. OnMessage는 procedure(Connection: TsgcWSConnection; const Text: string)이에요. OnError는 procedure(Connection: TsgcWSConnection; const Error: string)이에요. OnException은 procedure(Connection: TsgcWSConnection; E: Exception)이에요. 직접 입력하지 말고 IDE가 생성하게 하세요. 첫 프로젝트에서 가장 흔한 컴파일 오류가 매개변수를 더 쓰거나 빠뜨리는 거예요.
sgcWebSocket.pas, sgcWebSocket_Client.pas, sgcWebSocket_Server.pas에는 유닛 범위의 플랫폼 가드가 없고, 두 컴포넌트 모두 ComponentPlatforms(0)으로 등록되어 있어서 IDE가 특정 대상으로 제한하지 않아요. FireMonkey 클라이언트와 서버 데모는 Demos\01.WebSocket_Quick_Start\07.Firemonkey_Server_and_Client 아래에 포함되어 있어요. 라이브러리에서 플랫폼이 제한된 유일한 WebSocket 컴포넌트는 Win32와 Win64용 TsgcWebSocketClient_WinHTTP예요.
TLS := True로 설정하고 Port를 TLS 포트로 지정하세요. 그다음 TLSOptions.IOHandler로 TLS 백엔드를 선택해요. OpenSSL은 모든 플랫폼에서 동작하며 Windows에서는 실행 파일 옆에 libcrypto-3.dll과 libssl-3.dll이 필요해요. SChannel은 Windows 전용이고 추가로 배포할 것이 없어요. Apple과 Android 네이티브 핸들러는 Enterprise 기능이에요.
Active := True를 설정하기 전에 이벤트 핸들러를 먼저 할당하세요. 그러지 않으면 핸들러가 붙기 전에 첫 OnConnect가 발생할 수 있어요. 콘솔 애플리케이션에서는 클라이언트가 자체 스레드에서 실행되므로 메인 스레드를 계속 살려 두어야 해요. 그래서 샘플이 Readln으로 끝나요.
WatchDog.Enabled := True로 설정하고, 기본값이 너무 공격적이면 WatchDog.Interval과 WatchDog.Attempts를 조정하세요.
Demos\ 아래에 있어요. 이 페이지에서 사용한 쌍은 01.WebSocket_Quick_Start\01.Server_and_Client_Chat이에요. 일찍 열어 볼 만한 것으로는 자격 증명을 검사하는 서버를 위한 06.Authentication, 크로스플랫폼 클라이언트를 위한 07.Firemonkey_Server_and_Client, 일부 연결에만 브로드캐스트하는 12.Groups가 있어요.