TsgcWSPClient_MQTT › Methods › Subscribe

Subscribe Method

Subscribes the client to one or more topic filters at the requested QoS.

Overloads

Overload 1

Syntax

function Subscribe(const aTopic: String; aQoS: TmqttQoS = mtqsAtMostOnce; const aSubscribeProperties: TsgcWSMQTTSubscribe_Properties = nil) : Word;

Parameters

Name	Type	Description
`aTopic`	`const String`	Topic filter to subscribe to; single-level (+) and multi-level (#) wildcards are supported.
`aQoS`	`TmqttQoS`	Maximum QoS the broker should deliver for matching messages. Defaults to mtqsAtMostOnce.
`aSubscribeProperties`	`const TsgcWSMQTTSubscribe_Properties`	Optional MQTT 5.0 properties such as Subscription Identifier, No Local flag, Retain As Published or Retain Handling. Pass nil to use defaults.

Return Value

Packet identifier of the SUBSCRIBE packet. Correlate it with the grant reported through OnMQTTSubscribe to learn the QoS the broker actually assigned. (Word)

Remarks

Single-topic overload, the most common form. Incoming messages are surfaced through OnMQTTPublish (or OnMQTTPublishEx for MQTT 5.0). The broker may downgrade QoS if it does not support the requested level or if ACL rules apply.

Example

MQTT.Subscribe('sensors/+/temperature', mtqsAtLeastOnce);

Overload 2

Syntax

function Subscribe(aTopics: TsgcWSTopics): Word;

Parameters

Name	Type	Description
`aTopics`	`TsgcWSTopics`	Collection of topic filters with individual QoS settings, sent as a single SUBSCRIBE packet.

Return Value

Packet identifier of the batched SUBSCRIBE packet; used to correlate all grants received through OnMQTTSubscribe. (Word)

Remarks

Batch overload that subscribes to several filters in one round-trip. Prefer it over a loop of single-topic calls to cut network chatter and give the broker the chance to return a full reason-code list in a single SUBACK.

Example

oTopics := TsgcWSTopics.Create;
try
  oTopics.Add('sensors/#', mtqsAtLeastOnce);
  oTopics.Add('alerts/#', mtqsExactlyOnce);
  MQTT.Subscribe(oTopics);
finally
  oTopics.Free;
end;

Back to Methods