PUBLISH Publish message

A PUBLISH message is sent by a client to a broker for distribution to interested subscribers. Each PUBLISH message is associated with a topic name (also known as the Subject or Channel). This is a hierarchical name space that defines a taxonomy of information sources for which subscribers can register an interest. A message that is published to a specific topic name is delivered to connected subscribers for that topic.

To maintain symmetry, if a client subscribes to one or more topics, any message published to those topics are sent by the broker to the client as a PUBLISH message.

Fixed header

The table below shows the fixed header format.

bit 7 6 5 4 3 2 1 0
byte 1 Message type (3) DUP flag QoS level RETAIN
  0 0 1 1 0 0 1 0
byte 2 Remaining Length
QoS level
Set to 1.
DUP flag
Set to zero (0). This means that the message is being sent for the first time.

For messages with QoS level 1 or level 2 that are being re-sent because a failure has been detected, the DUP bit is set to 1. This indicates to the broker that the message might duplicate a message that has already been received. The significance of this information to the broker depends upon the QoS level. The DUP bit is not used for messages with QoS level 0.

RETAIN flag
Set to zero. This means do not retain.
Remaining Length field
The length of the variable header plus the length of the payload. It can be a multibyte field.

Variable header

The variable header contains the following fields:

Topic name
A UTF-encoded string.
Message ID
Present for messages with QoS level 1 and QoS level 2.

Typically, the protocol library is responsible for generating the Message ID and passing it back to the publishing application, possibly as a return handle. This approach avoids the risk of multiple applications, or publishing threads, running on a single client generating duplicate Message IDs.

A Message ID must not be used in the variable header for messages with QoS level 0.

The Message ID is a 16-bit unsigned integer, which typically increases by exactly one from one message to the next, but is not required to do so. The ordering of the 2 bytes of the Message Identifier is MSB, then LSB (big-endian).

Message ID 0 (that is, 0x0000) is reserved as an invalid Message ID, and must not be used.

The table below shows an example variable header for a PUBLISH message.

Field Value
Topic Name: "a/b"
QoS level 1
Message ID: 10

The format of the variable header in this case is shown in the table below.

  Description 7 6 5 4 3 2 1 0
Topic Name
byte 1 Length MSB (0) 0 0 0 0 0 0 0 0
byte 2 Length LSB (3) 0 0 0 0 0 0 1 1
byte 3 'a' (0x61) 0 1 1 0 0 0 0 1
byte 4 '/' (0x2F) 0 0 1 0 1 1 1 1
byte 5 'b' (0x62) 0 1 1 0 0 0 1 0
Message Identifier
byte 6 Message ID MSB (0) 0 0 0 0 0 0 0 0
byte 7 Message ID LSB (10) 0 0 0 0 1 0 1 0

Payload

Contains the data for publishing. The content and format of the data is application specific. The Remaining Length field in the fixed header includes both the variable header length and the payload length.

Response

The response to a PUBLISH message depends on the QoS level. The table below shows the expected responses.

QoS Level Expected response
QoS 0 None
QoS 1 PUBACK
QoS 2 PUBREC

Actions

PUBLISH messages can be sent either from a publisher to the broker, or from the broker to a subscriber. The action of the recipient when it receives a message depends on the QoS level of the message:

QoS 0
Make the message available to any interested parties.
QoS 1
Log the message to persistent storage, make it available to any interested parties, and return a PUBACK message to the sender.
QoS 2
Log the message to persistent storage, do not make it available to interested parties yet, and return a PUBREC message to the sender.

If the broker receives the message, interested parties means subscribers to the topic of the PUBLISH message. If a subscriber receives the message, interested parties means the application on the client which has subscribed to one or more topics, and is waiting for a message from the broker.