이 패키지에는 네이티브 메시징 클라이언트가 일곱 개 들어 있어요. MQTT가 가장 빠르게 동작하는 결과를 볼 수 있는 길이라서 이 페이지에서는 MQTT를 다뤄요. 브로커에 연결하고, 토픽을 구독하고, 메시지를 게시한 뒤 그 메시지가 돌아오는 것을 지켜봐요. AMQP, Kafka, STOMP도 같은 두 컴포넌트 구조를 따라요.
많은 분이 여기서 헷갈려 해요. 프로토콜 컴포넌트는 MQTT를 말하고, 별도의 클라이언트 컴포넌트가 소켓을 소유해요. 둘은 할당 한 줄로 연결해요.
SGC MQ 팔레트 페이지의 TsgcWSPClient_MQTT예요. Connect, Subscribe, Publish, UnSubscribe와 MQTT 이벤트 열세 개를 제공해요.
WebSocket 위의 MQTT에는 TsgcWebSocketClient를, TCP 위의 일반 MQTT에는 TsgcTCPClient를 쓰세요. Host와 Port는 이 컴포넌트에 설정해요.
MQTT.Client := WSClient;예요. 그 뒤에는 프로토콜의 메서드를 호출하는 것이 아니라 WSClient.Active := True를 설정해서 연결을 열어요.
sgcWebSocket_Protocol_MQTT_Client.pas에는 플랫폼 가드가 없고 조건부 Windows import만 있으며, 컴포넌트는 ComponentPlatforms(0)으로 등록돼요. 모든 대상에서 컴파일돼요.
에디션 열은 각 프로토콜을 제어하는 define이며, Source/sgcVer.inc에서 그 define이 있는 줄 번호도 함께 적었어요.
| 항목 | 값 |
|---|---|
| IDE | Delphi 7부터 RAD Studio 13까지, 그리고 C++Builder 2007부터 13까지. |
| Uses 절 | TsgcWSPClient_MQTT에는 sgcWebSocket_Protocols, 클라이언트에는 sgcWebSocket, TsgcWSConnection에는 sgcWebSocket_Classes, TmqttQoS에는 sgcWebSocket_Types. |
| MQTT 에디션 | SGC_MQTT는 717번째 줄에 정의되어 있으며, 675번째 줄부터 724번째 줄까지 이어지는 {$IFDEF SGC_EDT_STD} 블록 안에 있어요. 따라서 Standard 이상이에요. 블록은 누적 방식이라 Professional, Enterprise, All-Access에도 포함돼요. |
| 다른 프로토콜 | 모두 같은 Standard 블록 안에 있어요. 716번째 줄의 SGC_STOMP, 718번째 줄의 SGC_AMQP, 719번째 줄의 SGC_AMQP1, 720번째 줄의 SGC_KAFKA, 715번째 줄의 SGC_WAMP예요. 이 중 Enterprise 기능은 하나도 없어요. |
| 에디션, 독립 패키지 | sgcMQ 제품은 855번째 줄에서 SGC_PACK_MQ를 정의하고, 959번째 줄부터 966번째 줄까지의 자체 블록이 같은 프로토콜 define 다섯 개를 켜요. |
| 플랫폼 | MQTT 클라이언트 유닛에는 유닛 범위의 플랫폼 가드가 없어요. uses 절의 유일한 조건문은 {$IFDEF MSWINDOWS}Windows, {$ENDIF}예요. |
직접 설치하지 않고도 테스트할 브로커가 필요한가요? 포함된 MQTT 데모는 www.esegece.com의 공개 테스트 브로커를 가리켜요. WebSocket 위의 MQTT는 15675 포트예요.
sgcMQ는 sgcWebSockets 설치 프로그램에 들어 있고 독립 패키지로도 제공돼요. 어느 쪽이든 설치 방식은 같아요.
다운로드한 파일을 폴더에 압축 해제하세요. 아래에서는 이 폴더를 {$DIR}이라고 불러요.
Tools, Options, Library로 이동해요. {$DIR}\source와 사용하는 IDE의 lib 폴더를 추가하세요. 예를 들면 {$DIR}\libD13\$(Platform)이에요.
{$DIR}\Packages\ 아래에서 IDE 버전에 맞는 패키지 그룹을 여세요. 런타임 .dpk를 먼저 컴파일하고 그다음 디자인 타임 dcl 패키지를 설치해요.
에디션이 활성화한 프로토콜 클라이언트가 들어 있는 SGC MQ 페이지가 나타나요. Standard 빌드 이상에는 TsgcWSPClient_MQTT가 있어요.
{$DIR}\Demos\02.WebSocket_Protocols\08.MQTT_Client를 여세요. 아래 코드가 여기서 나왔고, 이미 실제 테스트 브로커를 가리키도록 설정되어 있어요.
프로토콜을 클라이언트에 연결하고, 연결을 열고, 토픽을 구독한 다음 그 토픽에 게시해요. 메시지는 OnMQTTPublish로 돌아와요.
uses
Classes, SysUtils,
// sgc
sgcWebSocket, sgcWebSocket_Classes, sgcWebSocket_Protocols,
sgcWebSocket_Types, sgcWebSocket_Protocol_MQTT_Client,
sgcWebSocket_Protocol_MQTT_Message;
procedure TfrmClientPROTOCOL.FormCreate(Sender: TObject);
begin
WSClient := TsgcWebSocketClient.Create(Self);
WSClient.Host := 'www.esegece.com';
WSClient.Port := 15675;
WSClient.TLS := False;
// ... attach the client to the MQTT protocol
MQTT.Client := WSClient;
// ... and THIS is what opens the connection.
// There is no Connect call on the protocol component.
WSClient.Active := True;
end;WebSocket이 아니라 TCP 위의 일반 MQTT를 쓰려면 sgcTCP_Client_WS의 TsgcTCPClient를 대신 만들고 MQTT.Client가 그것을 가리키게 하세요. 나머지는 바뀌지 않아요. 두 컴포넌트가 분리되어 있는 이유가 바로 이거예요.
procedure TfrmClientPROTOCOL.btnSubscribeClick(Sender: TObject);
begin
MQTT.Subscribe('sgc/quickstart');
end;
procedure TfrmClientPROTOCOL.btnPublishClick(Sender: TObject);
begin
// topic, payload, QoS, retain
MQTT.Publish('sgc/quickstart', 'hello from Delphi',
mtqsAtLeastOnce, False);
end;
procedure TfrmClientPROTOCOL.btnUnsubscribeClick(Sender: TObject);
begin
MQTT.UnSubscribe('sgc/quickstart');
end;Publish는 패킷 식별자인 Word를 반환하고 기다리지 않아요. PublishAndWait는 Boolean을 반환하고 브로커가 확인할 때까지 차단하며, 타임아웃 기본값은 10초예요. TmqttQoS는 sgcWebSocket_Types에서 와요.
procedure TfrmClientPROTOCOL.MQTTMQTTConnect(Connection: TsgcWSConnection;
const Session: Boolean; const ReasonCode: Integer;
const ReasonName: String;
const ConnectProperties: TsgcWSMQTTCONNACKProperties);
begin
memoLog.Lines.Add('#connected: ' + ReasonName);
end;
procedure TfrmClientPROTOCOL.MQTTMQTTSubscribe(Connection: TsgcWSConnection;
aPacketIdentifier: Word; aCodes: TsgcWSSUBACKS;
SubscribeProperties: TsgcWSMQTTSUBACKProperties);
begin
memoLog.Lines.Add('#subscribed: ' + IntToStr(aPacketIdentifier));
end;
procedure TfrmClientPROTOCOL.MQTTMQTTPublish(Connection: TsgcWSConnection;
aTopic, aText: string;
PublishProperties: TsgcWSMQTTPUBLISHProperties);
begin
memoLog.Lines.Add(aTopic + ': ' + aText);
end;처음에 중요한 이벤트는 이 세 개예요. 확인 응답 흐름, 연결 해제, MQTT 5.0 인증을 위한 이벤트가 아홉 개 더 있어요. 매개변수 목록이 길고 이벤트마다 속성 객체가 다르므로 핸들러는 IDE가 생성하게 하세요.
세 탭 모두 포함된 데모 Demos\02.WebSocket_Protocols\08.MQTT_Client\uClientMQTT.pas에서 가져온 것이며 폼 컨트롤은 리터럴로 바꿨어요. 그 프로젝트에서는 MQTT 객체를 폼에 올려 두었는데, 코드로 만들어도 똑같이 동작해요.
이벤트 두 개로 브로커가 연결을 받아 주었는지, 토픽이 활성 상태인지 알 수 있어요.
OnMQTTConnect브로커가 세션을 수락했어요. 수락하지 않았다면 ReasonCode와 ReasonName이 이유를 알려 주며, 소켓이 그냥 끊기는 것보다 훨씬 유용해요.
OnMQTTSubscribe구독이 승인되었어요. TsgcWSSUBACKS인 aCodes가 토픽별 브로커 응답을 담고 있어서, 거부된 구독도 조용히 넘어가지 않고 눈에 보여요.
OnMQTTPublish메시지가 도착했어요. 방금 구독한 토픽에 게시하면 바로 돌아오며, 클릭 한 번으로 전체 경로가 증명돼요.
QoS 1과 2에서는 전달 확인이 나중에 OnMQTTPubAck, OnMQTTPubRec, OnMQTTPubRel, OnMQTTPubComp로 와요. 대신 차단 호출이 필요하면 PublishAndWait를 쓰세요.
실패한 첫 연결은 거의 다 여섯 가지 문제 중 하나가 원인이에요.
연결이 아직 열리지 않은 거예요. 소켓은 프로토콜 컴포넌트가 아니라 클라이언트가 열어요. WSClient.Active := True로 설정하고, 구독하기 전에 OnMQTTConnect를 기다리세요.
MQTT.Client를 할당하지 않았어요. 그 한 줄이 프로토콜을 전송 계층에 연결해 주며, 없으면 프로토콜이 쓸 곳이 없어요.
대부분의 브로커에서 WebSocket 위의 MQTT와 일반 TCP 위의 MQTT는 포트가 서로 달라요. TCP에서는 1883과 8883이 흔히 쓰이고, WebSocket 엔드포인트는 전혀 다른 곳에 있어요. 포함된 데모는 WebSocket에 15675를 써요.
그런 이벤트는 없어요. 브로커에서 들어오는 메시지는 텍스트라면 OnMQTTPublish로, 원시 페이로드와 전체 메시지 객체가 필요하면 OnMQTTPublishEx로 도착해요.
확인 응답은 비동기로 와요. Publish는 패킷 식별자를 즉시 반환하고, 확인 응답은 나중에 OnMQTTPubAck, OnMQTTPubRec, OnMQTTPubRel, OnMQTTPubComp로 도착해요. 차단 호출을 원하면 PublishAndWait를 쓰세요.
대부분의 브로커는 클라이언트 식별자와 자격 증명을 요구해요. Authentication에 설정하고, 연결 시점에 클라이언트 식별자를 계산해야 한다면 OnMQTTBeforeConnect를 쓰세요.
같은 두 컴포넌트 구조가 패키지의 다른 모든 프로토콜에도 적용돼요.
MQTTVersion을 설정하면 요청과 응답 속성 객체를 사용할 수 있어요. 사용자 속성, 구독 식별자, 토픽 별칭, 사유 코드가 모두 노출돼요.
클라이언트가 두 개 있어요. RabbitMQ 스타일의 익스체인지와 큐를 위한 0.9.1, 그리고 더 새로운 와이어 프로토콜인 1.0이에요. 둘 다 MQTT와 같은 방식으로 클라이언트에 연결해요.
네이티브 Kafka 와이어 프로토콜 클라이언트, 그리고 RabbitMQ와 ActiveMQ용 브로커별 변형을 포함한 STOMP 1.0부터 1.2까지를 지원해요.
AWS IoT와 Azure IoT는 모두 MQTT를 사용하며, 라이브러리에는 서명과 인증을 대신 처리해 주는 전용 컴포넌트가 포함되어 있어요.
레퍼런스 페이지에는 모든 속성과 이벤트가 문서화되어 있어요. 데모 프로젝트는 다운로드 안의 Demos\02.WebSocket_Protocols 아래에 있어요.
레퍼런스, MQTT 클라이언트
TsgcWSPClient_MQTT의 모든 메서드, 속성, 이벤트.
|
열기 | |
| 레퍼런스, AMQP 0.9.1 익스체인지, 큐, 바인딩, 컨슈머. | 열기 | |
| 레퍼런스, AMQP 1.0 링크, 세션, 1.0 메시지 모델. | 열기 | |
| TsgcWSPClient_MQTT 컴포넌트 페이지 MQTT 클라이언트 전체 설명과, 여기서 연결되는 나머지 여섯 개 프로토콜 클라이언트. | 열기 | |
| 프로토콜 개요 서브 프로토콜 컴포넌트가 클라이언트나 서버에 연결되는 방식. | 열기 | |
| 온라인 도움말 자동 생성된 레퍼런스로, 항상 최신 릴리스와 일치해요. | 열기 |
함께 읽어 보세요. 게시하고 확인 응답 기다리기, AMQP 익스체인지와 큐, Kafka 클라이언트. 모든 제품에는 각자의 빠른 시작이 있으며, 시작하기 페이지에서 모아 볼 수 있어요.
TsgcWSPClient_MQTT는 MQTT 패킷을 인코딩하고 디코딩해요. TsgcWebSocketClient나 TsgcTCPClient는 소켓, 호스트, 포트, TLS 설정을 소유해요. 할당 한 줄로 둘을 연결해요. MQTT.Client := WSClient;예요.
Active := True를 설정하세요. 포함된 데모가 정확히 그렇게 해요. 프로토콜에도 Connect 메서드가 있지만 데모는 그것을 쓰지 않으며, 모든 샘플이 따르는 방법은 Active 설정이에요.
SGC_MQTT는 sgcVer.inc의 717번째 줄에 정의되어 있으며, 675번째 줄부터 724번째 줄까지 이어지는 SGC_EDT_STD 블록 안에 있어요. 유료 최저 등급인 Standard 에디션이고, 블록이 누적 방식이라 더 높은 에디션에도 모두 포함돼요. 716번째 줄의 STOMP, 718번째 줄의 AMQP, 719번째 줄의 AMQP 1.0, 720번째 줄의 Kafka도 모두 같은 블록에 있어요. 메시징 프로토콜 중 Enterprise 기능은 하나도 없어요.
OnMQTTPublish이며 시그니처는 procedure(Connection: TsgcWSConnection; aTopic, aText: String; PublishProperties: TsgcWSMQTTPUBLISHProperties)예요. OnMQTTMessage라는 이벤트는 없어요. 문자열이 아니라 원시 바이트나 전체 메시지 객체가 필요하다면 대신 OnMQTTPublishEx를 처리하세요.
Publish는 패킷 식별자인 Word를 반환해요. 전달 확인은 비동기로 와요. QoS 1에서는 OnMQTTPubAck로, QoS 2에서는 OnMQTTPubRec, OnMQTTPubRel, OnMQTTPubComp로 와요. 브로커가 확인할 때까지 차단하는 호출이 필요하면 PublishAndWait를 쓰세요. Boolean을 반환하고 기본값이 10초인 타임아웃을 받아요.
Publish의 세 번째 매개변수가 TmqttQoS이며, sgcWebSocket_Types.pas에 mtqsAtMostOnce, mtqsAtLeastOnce, mtqsExactlyOnce, mtqsReserved 멤버로 선언되어 있어요. 기본값은 mtqsAtMostOnce예요. Subscribe는 두 번째 매개변수로 같은 타입을 받아요.
sgcWebSocket_Protocol_MQTT_Client.pas에는 유닛 범위의 플랫폼 가드가 없고, uses 절의 유일한 조건문은 Windows import이며, 팔레트 컴포넌트는 ComponentPlatforms(0)으로 등록되어 있어서 IDE가 대상 플랫폼을 제한하지 않아요.
MQTTVersion을 설정하세요. 그러면 5.0 속성 객체를 사용할 수 있어요. 보낼 때는 ConnectProperties, 돌아올 때는 각 이벤트의 속성 매개변수예요. 예를 들면 OnMQTTConnect의 TsgcWSMQTTCONNACKProperties와 OnMQTTPublish의 TsgcWSMQTTPUBLISHProperties가 있어요.