Subscribe Method
Subscribes the component to the specified topic.
procedure Subscribe(TopicId: String; TopicIdType: Integer; QOS: Integer);
Remarks
This method subscribes the component to the TopicId using the given QoS level.
TopicIdType indicates the category of value specified in TopicId and may have the following values:
- 0: Topic name - a full topic name as described in RegisterTopic to be registered by the gateway.
- 1: Pre-defined topic id - id whose mapping to a topic name is known in advance by both the client and the gateway - no registration is necessary.
- 2: Short topic name - has a fixed length of two bytes and is short enough that no registration is necessary. To use one, simply set the correct TopicIdType and set the TopicId to a two-character string.
If the topic name option is used, the topic id returned with the SUBACK packet will be accessible in the SubscribedTopicId configuration setting. If a topic name with a wildcard character is used, SubscribedTopicId will be 0. When the gateway has a PUBLISH message with a topic name matching the wildcard to be sent to the client, it will follow the registration process described in TopicInfo.
Subscribe Examples
String fullTopicName = "full/topic/name";mqttsn1.Subscribe(fullTopicName, 0, 2); // subscribe with topic nameint assignedTopicId = mqttsn1.Config("SubscribedTopicId"); // map id to topic name usedmqttsn1.Subscribe(fullTopicName+"/#", 0, 2) // topic name with wildcard; SubscribedTopicId will be 0mqttsn1.OnTopicId += (s,e) => { // will fire before messages matching the wildcard are sent to the client int topicId = e.TopicId; String topicName = e.TopicName; // establish mapping between these};mqttsn1.Subscribe("aa", 2, 2); // subscribe with short topic name; no need for registration
Topic Filters
A topic filter is a string which can be passed to TopicId when TopicIdType is 0 and can match one or more topic names.
A topic filter is a case-sensitive string between 1 and 65535 characters long (per topic filter), and can include any character other than the null character. Certain characters have special meanings:
- / - The topic level separator
- # - The multi-level wildcard (zero or more levels)
- + - The single-level wildcard (exactly one level)
- Leading $ - Denotes a "system topic"
Note that both types of wildcards may be used in the same topic filter.
Topic Level Separators
The topic level separator, as its name implies, is used to separate a topic name (or in this case, filter) into "levels". This concept of topic names having levels is what allows topic filters to match multiple topics through the use of wildcards. For the examples in the next sections, assume the following topics exist:
- home/floor1
- home/floor1/livingRoom
- home/floor1/livingRoom/temperature
- home/floor1/kitchen/temperature
- home/floor1/kitchen/fridge/temperature
- home/floor2/bedroom1
- home/floor2/bedroom1/temperature
Multi-level Wildcards
The multi-level wildcard character is used at the end of a topic filter to make it match an arbitrary number of successive levels. For example, the topic filter home/floor1/# would match the following topics:
- home/floor1 (because it can match zero levels)
- home/floor1/livingRoom
- home/floor1/livingRoom/temperature
- home/floor1/kitchen/temperature
- home/floor1/kitchen/fridge/temperature
Here are some things to keep in mind when using a multi-level wildcard:
- # must always be the last character in the topic filter (e.g., home/floor1/#/livingRoom is not valid)
- # must always be preceded by a / (e.g., home/floor1# is not valid)
- # by itself is a valid topic filter, and will match all topics except system topics
Single-level Wildcards
The single-level wildcard character is used between two /s in a topic filter to make it any single level. For example, the topic filter home/floor1/+/temperature would match the following topics:
- home/floor1/livingRoom/temperature
- home/floor1/kitchen/temperature
Any number of single-level wildcards are supported in a topic filter. For example, the topic filter home/+/+/temperature would match the following topics:
- home/floor1/livingRoom/temperature
- home/floor1/kitchen/temperature
- home/floor2/bedroom1/temperature
Here are some things to keep in mind when using single-level wildcards:
- + must always be separated from other levels using /s (e.g., home/floor1+ is invalid, but +/floor1/+ is valid)
- + by itself is a valid topic filter, and will match all topics with exactly one level in their name except system topics
- Remember, topic names with a leading / have a zero-length string as their first level. So a topic named /people would be matched by the topic filter +/+, but not by +
- + must match exactly one level. So for example, the topic filter home/floor1/kitchen/+/temperature would match /home/floor1/kitchen/fridge/temperature, but not home/floor1/kitchen/temperature
QoS Values
QoS values set the service level for delivery of a message. For subscriptions, values range from 0 to 2 and have the following meanings:
| QoS Level | Description |
| -1 | Simple publish - No connection, registration or subscription needed. |
| 0 | At most once - The published message is sent once, and if it does not arrive it is lost. |
| 1 | At least once - Guarantees that the published message arrives, but there may be duplicates. |
| 2 | Exactly once - Guarantees that the publish message arrives and that there are no duplicates. |
A QoS value of -1 is not applicable to subscriptions.
Note that if this message is being resent, the SubscribeDUP configuration setting must be enabled. For more details on retransmission intervals and counts, see the MQTTSN specification.