Topic Alias is a way to reduce PUBLISH packet size.
Notifying capacity
There are two independent Topic Alias capacities.
Broker to Client Topic Alias
The client can set the Topic Alias Maximum
property to a value greater than 0 in the CONNECT packet. This means the client can receive PUBLISH packets with the Topic Alias
property set to a value less than or equal to the Topic Alias Maximum
. The broker can then send PUBLISH packets using the Topic Alias
property.
If the broker does not receive a CONNECT packet with the Topic Alias Maximum
property set to a value greater than 0, the broker cannot use Topic Alias
.
Client to Broker Topic Alias
The broker can set the Topic Alias Maximum
property to a value greater than 0 in the CONNACK packet. This means the broker can receive PUBLISH packets with the Topic Alias
property set to a value less than or equal to the Topic Alias Maximum
. The client can then send PUBLISH packets using the Topic Alias
property.
If the client does not receive a CONNACK packet with the Topic Alias Maximum
property set to a value greater than 0, the client cannot use Topic Alias
.
Using Topic Alias
Register/Overwrite
When you set the TopicName
filed and Topic Alias
property in the PUBLISH packet, the mapping is registered. If the Topic Alias
is already mapped, the mapping is overwritten.
Use
When you set an empty (zero length) TopicName
field and Topic Alias
property in the PUBLISH packet, the receiver needs to extract the TopicName
corresponding to the Topic Alias
.
In this case, the packet size is usually reduced, especially if the TopicName
is long.
async_mqtt Support
Setup
If you are using async_mqtt as the client, all you need to do is set the Topic Alias Maximum
property in the CONNECT packet.
If you are using async_mqtt as the server (broker), all you need to do is set the Topic Alias Maximum
property in the CONNACK packet.
Then the mapping functionality is automatically set up.
set_auto_map_topic_alias_send(bool)
When you call this function with the argument true
, the Topic Alias
is automatically allocated and used when you send a PUBLISH packet. If you run out of all Topic Alias
values, the oldest mapping is automatically replaced using the LRU (Least Recently Used) algorithm.
set_replace_map_topic_alias_send(bool)
When you call this function with the argument true
, the Topic Alias
is automatically used if the mapping is registered when you send a PUBLISH packet.
Manual Use
You can register/use Topic Alias
manually by setting the PUBLISH packet. This works well with the above two automatic functionalities.
Pitfall
async_mqtt has already solved this problem. This is an implementation note.
If the client/broker keeps the session, any halfway QoS1 and QoS2 PUBLISH packets should be resent just after reconnection. What happens if the PUBLISH packet uses a Topic Alias
? In this case, the TopicName
is empty. The counterpart’s Topic Alias Maximum
could be reduced (or removed) upon reconnection. The MQTT spec states that the lifetime of a Topic Alias
mapping should end on disconnect. In other words, the lifetime of a Topic Alias
mapping is the same as the lifetime of the connection, not the session.
So, if the client/broker sends a PUBLISH packet with an empty TopicName
and Topic Alias
property just after reconnection, it is a protocol violation.
To solve this problem, the client/broker needs to extract the TopicName
from the Topic Alias
property when sending and create a new PUBLISH packet containing the extracted TopicName
, and remove the Topic Alias
property from the sending PUBLISH packet. When resending, use the stored (non-Topic Aliased) packet.
This process is automatically handled by async_mqtt internally. Users don’t need to worry about this issue.
async_mqtt does expected behavior automatically.