Various message types require additional information as part of
the header section of the message, before the application-defined Payload.
The fields that are present in each type of message are defined in the
specification for that message type. The complete collection of fields
and their data types is specified here.
In a message where several Variable Header fields appear, they must appear strictly in the order specified in this section.
Note that the variable-length Remaining Length field is not part of
the Variable Header, and so its bytes do not contribute to the byte count
of the Remaining Length value, which only considers the Variable Header
and Payload portions of the message. See the Fixed
Header section for more information.
UTF-encoded string to identify the name of the
protocol that is being used.
This is defined to be "MQIpdp", capitalised as shown. The letters
stand for Message Queuing Integrator Pervasive Device Protocol, for what
it's worth.
See the UTF section for more information.
The Version field indicates the current revision level of the protocol
being used by the client. The Version field is an 8 bit unsigned value
representing the Protocol Version. For this version of the protocol, the
Version field will contain a value of 2 (0x02).
| bit |
|
|
|
|
|
|
|
|
|
|
||||||||
|
|
|
|
|
|
|
|
|
|
The Connect Flags allow various options to be selected when a client
connects to the broker.
The TNCOMP Request flag is bit 0 of the Connect Flags byte.
The TNCOMP Request flag is used to indicate that the client wishes to make use of the Topic Name compression algorithm (described below). A 1 indicates that the client may wish to compress Topic Names, a 0 indicates that the client will never compress a Topic Name.
In this level of the Protocol, Topic Name compression is not available,
and so the value of this flag is always 0.
| bit |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Request |
||
|
|
|
|
|
|
|
|
|
|
The upper 2 bits of this byte are currently unused in this version
of the protocol. They are, however reserved for future use.
The Clean Start flag is bit 1 of the Connect Flags byte.
The Clean Start flag provides a way for the client to go back to a known,
"clean" state with the broker. If the flag is set, the broker will discard
any outstanding messages for that client, delete all subscriptions for
that client, and reset the Message ID to 1. The client will then be able
to proceed without risk the of any data from previous connections interfering
with the current connection.
| bit |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Request |
||
|
|
|
|
|
|
|
|
||
The upper 2 bits of this byte are currently unused in this version
of the protocol. They are, however reserved for future use.
The "Will" flag is bit 2 of the Connect Flags byte.
The "Will" message is a mechanism by which a client can define a message
to be published on its behalf by the broker, in the event of the client's
"death". We define "death" in this context to mean that either an I/O
error is encountered by the broker during communication with the client,
or
the client fails to communicate within the Keep Alive Timer schedule
(see below). The receipt of a DISCONNECT packet from the client does
NOT trigger the sending of the Will message.
If the Will flag is set, then the Will QoS and Will RETAIN
fields in the Connect Flags byte must be provided, as must the Will
Topic and Will Message fields in the Payload.
| bit |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Request |
||
|
|
|
|
|
|
|
|
||
The upper 2 bits of this byte are currently unused in this version
of the protocol. They are, however reserved for future use.
The "Will" QoS field is bits 4 and 3 of the Connect Flags byte.
The Will QoS field is used by a connecting client to specify the Quality of Service at which the Will Message (part of the Payload of the CONNECT message) will be sent in the event of the untimely death (involuntary disconnection) of this client.
If the Will Flag is set, then this field is mandatory, otherwise its value is disregarded.
Will QoS can take the value 0 (0x00), 1 (0x01), or 2 (0x02), just like
an ordinary QoS on a PUBLISH.
| bit |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Request |
||
|
|
|
|
|
|
|
|||
The upper 2 bits of this byte are currently unused in this version
of the protocol. They are, however reserved for future use.
The "Will" RETAIN flag is bits5 of the Connect Flags byte.
The Will RETAIN flag is used to indicate if the Will Message, published by the broker on behalf of the client if it becomes unexpectedly disconnected, is to be RETAINed by the broker or not. See discussion of RETAIN in the PUBLISH section.
If the Will Flag is set, then this field is mandatory, otherwise
its value is disregarded.
| bit |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Request |
||
|
|
|
|
|
|
|
|
||
The upper 2 bits of this byte are currently unused in this version
of the protocol. They are, however reserved for future use.
The Keep Alive timer is measured in seconds, and is the means by which a client tells the broker the maximum time interval between receiving messages from this client. This gives the broker a way of detecting that the network connection to a client has dropped, without having to wait for the long TCP/IP timeout. It is the responsibility of the client to ensure that it sends some kind of message within each Keep Alive time period. If there is not going to be a data-related message within the time period, then the client should send a PINGREQ message, which will be acknowledged by the broker with a PINGRESP.
If the broker does not hear from this client within 1.5 times the Keep Alive time period (i.e. the client is allowed half a time period's "grace"), it performs the disconnection processing that it would have done if the client had sent a DISCONNECT message. Note that this does not impact any of the client's subscriptions. See the DISCONNECT section for more details.
The Keep Alive timer is a 16-bit value representing the number of seconds
for the timeout. This allows timeouts up to around 18 hours. The
appropriate timeout value is application specific, but it is anticipated
that timeouts would be of the order of a few minutes.
A Keep Alive time of 0 indicates that there will be no Keep Alive timeout
processing, i.e. the broker will not disconnect a client due to elapsed
time.
The ordering of the 2 bytes of the Keep Alive Timer is MSB, then LSB
(big-endian).
| bit |
|
|
|
|
|
|
|
|
|
|
||||||||
|
|
||||||||
The TNCOMP Response flag is used to indicate that the broker has granted the client's request to make use of the Topic Name compression algorithm (described below). A 1 indicates that the client is permitted to compress Topic Names, a 0 indicates that the client must not compress any Topic Name.
In this level of the Protocol, Topic Name compression is not available,
and so the value of this flag is always 0.
| bit |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Response |
|
|
|
|
|
|
|
|
|
|
The upper 7 bits of this byte are currently unused in this version
of the protocol. They are, however reserved for future use.
This field defines a one byte unsigned return code. The meaning of the
various values are specific to the message type.
A return code of 0 can usually be expected to mean "success".
See the individual message specifications for more information.
| bit |
|
|
|
|
|
|
|
|
|
|
||||||||
For a PUBLISH message, the Topic Name is the key indicates the information channel to which the data in the Payload is being published. It is the key which subscribers use to identify the information channels on which they wish to receive published information.
The Topic Name has an upper length limit of 32,767 characters. This should not be cause any problems in practice.
The Topic Name can take one of two forms, according to the setting of
the TNCOMP flag in the CONNECT message, and
subsequently confirmed in the CONNACK message.
See the relevant sections for full details.
See the UTF section for more information.
If TNCOMP (Topic Name COMPression) is set, then the Topic Name may be compressed to potentially reduce the size of the message. Even though compression is permitted in the session, the Topic Name is not necessarily compressed. The topmost bit of the first byte of the Topic Name string is used to indicate if compression has been used. A 0 in this position indicates no compression, and the Topic Name is a simple UTF representation. A 1 in this position indicates that the string has been compressed in the following manner.
The content of the string (after the length bytes) is first of all XOR-d with the string that was previously sent. Care must be taken in a multi-process or multi-threaded environment that buffer contents are in sync at the client and broker, possibly by implementing this compression at the protocol library level, rather than in the application.
The resulting string is the run-length encoded... need
to think some more about this!
The Message Identifier field is only present in messages where the QoS bits in the Fixed Header indicate QoS 1 or QoS 2. See the QoS section for more information.
The Message Identifer is a 16 bit unsigned integer, which will typically increase, but is not required to increase by exactly one from one message to the next. This assumes that there will never be more than 65,535 messages "in flight" between one particular client-broker pair at any time.
The ordering of the 2 bytes of the Message Identifier is MSB, then LSB (big-endian).
Message ID 0 is reserved as an invalid Message ID, and must not be used.
| bit |
|
|
|
|
|
|
|
|
|
|
||||||||
|
|
||||||||