3 MQTT Control Packets

3.1 CONNECT – Connection Request

客户端与服务端建立连接后，CONNECT包为客户端发送给服务端的第一个包。

客服端经由一个网络连接，只可发送一次CONNECT包，服务端必须将第2个客户端发送的CONNECT包识别为协议错误，并关闭网络连接。

负荷包括一个或多个编码域，他们制定唯一的客户端ID， 一个遗愿话题(will topic), 遗愿负荷数据(will Payload), 用户名，密码。 除客户端ID外，其他都可省略，他们存在有可变头的标记决定。

3.1.1 CONNECT Fixed Header

剩余长度域： 可变头 + 负荷数据长度， 可变字节整数。

3.1.2 CONNECT Variable Header

CONNECT按顺序包括如下域:

• 协议名称(protocol name)
• 协议等级(protocol levle)
• 连接标记 Connect Flags
• keep alive
• properties

3.1.2.1 Protocol Name

• UTF-8编码字符串，值:”MQTT”, 大写；
• 该字符串，偏置及长度在未来版本的MQTT规范中不会更改。
• 支持多协议的服务端，可使用协议名称判断是否为MQTT数据。
• 当服务端不想接受CONNECT，但仍然想表明其为MQTT服务端，它可发送CONNACK包（包含消息码0X84：不支持的协议版本），然后关闭网络连接。

3.1.2.2 Protocol Version

1字节，代表客户端使用的协议版本，当前版本为5.0， 协议：5

• 服务端必须可支持多个版本的MQTT协议，并使用协议版本来区分客户端使用的MQTT协议版本。
• 如果协议版本不是5，服务端不想接受CONNECT包，返回CONANCK包括（消息码：0X84）,然后关闭网络连接。

3.1.2.3 Connect Flags

连接标记包括多个参数指定MQTT连接行为，它同时标识负荷域是否存在。

• 服务端必须验证CONNECT 包的保留位已置0，如未置0，则认为其为非法包（Malformed packet），即参考4.13进行错误处理

3.1.2.4 Clean Start

位置： bit1

• 接收到 clean start置1的CONNECT包，客户端和服务端必须丢弃已有会，重新启动新会话，同时如clean start置1， CONNACK的session 标记必须置0.
• 如果当前接收CONNECT包的 clean start置0且已有会话与该客户端ID相关，服务端必须要基于当前已有会话状态重新与客户端进行通信。

3.1.2.5 Will Flag

如果Will Flag置1标识服务端必须存储相关话题的遗愿消息。遗愿消息包括 will properties, will topic, 连接包中负荷中的will payload fields。

在网络连接突然关闭或者对话结束后遗愿等待时间到后，遗愿消息必须发布，除非服务端接收到DISCONNECT包（消息码:0x00, 正常断开）后删除了遗愿消息。

以下场景需发布遗愿消息；

• I/O错误或者服务端识别到网络失败。
• Keep Alive time.时间内客户端未能保存通信。
• 客服端关闭网络连接前未先发送正常断开的DISCONNECT包（消息码:0x00）.
• 服务端关闭网络连接前未接收到一个正常的DISCONNECT包。
• 如will flag置1， will properties, will topic, will payload域必须存在于负荷中。
• 当will 消息发布后后服务端接收到正常DISCONNECT包时，服务端必需将遗愿消息从存储对话状态移除。
• 在网络关闭且遗愿等待超时时间到或者对话结束，二者任一发生，服务必须立即发布will消息。
• 服务端可能延迟遗愿消息发布直到重启，如果发生这样的情况，服务器失败和遗愿消息发布见可能存在延迟。
• 客户端可以使用遗愿消息来告知对话已经超时，通过设置遗愿延迟时间大于对话超时时间，病假发送DISCONNECT包（消息码：0x04, 使用遗愿消息断开）。

3.1.2.6 Will QoS

位置： bit4:3

指定遗愿消息QoS服务等级。

will flag : 0, will QoS 必须为0

will flag: 1, will QoS可谓0， 1， 2，值为3为非法包需进行错误处理

3.1.2.7 Will Retain

位置： bit, 遗愿保留标记

will flag:0, will retain :0

will falg:1, will retain: 0, 服务端将遗愿消息作为非保存消息发布。

will flag: 1, will retian:1, 服务端将遗愿消息作为保存消息发布

3.1.2.8 User Name Flag

位置:bit 7, 置0；标识负荷数据无用户名称；置1负荷数据必须有用户名称

3.1.2.9 Password Flag

位置:bit 6, 置0；标识负荷数据无密码；置1负荷数据必须有密码。

V5版本支持无用户密码发送，V3.1.1不支持，这体现密码作为加密而非密码使用。

3.1.2.10 Keep Alive

2字节整数，标识时间间隔，单位s, 为包键最大允许的超时间隔。

• 应由客户端保证包间发送间隔不超过keep alive 值。
• 如果任意其他控制中keep alive为0或无，客户端必须发送PINGREQ包。
• 服务端在CONNACK中必须在CONNACK中需返回一个服务端的keep alive时间，客户端必须使用此值替换本省的keep alive值。
• 客户端可随时发送PINGREQ，无视keep alive值，检测PINGRRESP响应来确认服务端和网络是否可用。
• 如果keep alive值为0且服务端在1个半keep alive生命周期内，服务端未接收到MQTT的控制包，服务端需认为网络实现且必须关闭网络连接。
• 如果客户端发送PINGREQ后，在一定时间内为接收到PINGRESP响应包，它需关闭与服务端的网络连接。
• 如果生命周期保持时间为0，客户端不必强制发送MQTT控制包。
• 服务端可能由于其他原因断开客户端，例如其下线，设置keep alive值并不能保证客户端保持连接。
• keep alive值根据应用决定，一般为几分钟，最大值65535，时间为18小时12分15秒。

3.1.2.11 CONNECT Properties

未包含会话超时时间，默认为0， 当设置为0或无，会话在网络关闭后结束。

• 如果会话超时值为0xFFFFFFFF, 会话不超时。
• 当会话超时时间大于0时，客户端和服务端必须在网络关闭后保存会话状态。
• 客户端如只需在连接期间处理消息，则置1 clean start及会话超时间隔设置为0。它在连接前不会接收应用消息，同时每次连接后需重新订阅话题。
• 客户端可能使用一个断续不可靠的网络与服务端连接。客户端可使用一个短会话超时时间，以便网络可用是重新连接同时继续可靠的消息传递。如果客户端不重连，允许会话超时，应用消息会丢失。
• 当一个客户端以长会话超时时间连接，即要求断开连接的一段时间内，服务端保持MQTT会话状态 。客服端如需在稍后一定时间内重连服务端，则需使用长会话超时连接。客户端无需在断开后继续使用会话，她需使用0值会话超时断开。

• 客服端需使用CONNACK的会话存在标记，来确定服务端是否保存该客户端的会话状态。

客户端应避免实现自有的会话超时，同时应该遗留服务端返回的Session 存在标记，以此确定会话是否超时。

• 33（0x21）, 最大接收标识，后接2字节整数代表最大可接收值。
• 包括大于一个的最大值为协议错误。

客户端使用该值限制需同时处理QoS1和QoS2等级数量。对于等级QoS2则不限制。

最大可接收数值对当前网络连接使用，如无缺省为65535.

• 包大小为MQTT控制的总字节数，如果客户端接收到一个超过限制的包，客户端返回DISCONNECT (消息码为0x95)。
• 发送包太大时，服务必须丢弃不发送，同时将其认为消息已发送。

3.1.2.11.5 话题别名最大值(Topic Alias Maximum)

34(0x22),字节，话题别名最大值标识，后接2字节整数代表话题别名最大值 ，协议只可包含不超过一个改参数，缺省默认0.

该值表明客服端可接受的服务端发送的最大话题别名值，客户端使用其来限制连接可保持的话题别名数量。

服务端发送PUBLISH包中的话题别名不可超过话题别名最大值，如果话题别名最大值为0，服务端不可发送任何话题别名给客户端。

3.1.2.11.6 Request Response Information

25（0x19）,字节，请求响应信息标识，后跟一字节，值为0或1，协议帧只可包含不超过一次改参数，缺省默认0。

客户端使用该参数请求服务端在CONNACK中返回响应信息， 值为0则表明服务端不可返回响应消息，值为1服务端可在CONNACK中返回消息。

3.1.2.11.7 Request Problem Information

23（0x17）,字节，请求故障信息标识， 后接一个字节，值为0或1，协议只可包含不超过一次，缺省默认1.

• 客户端使用该参数标识失败时原因字符或用户属性是否发送，
• 值为0，服务端可在CONNACK或DISCONNECT包中返回原因字符串或用户属性，但不可在除PUBLIASH, CONNACK或DISCONNECT外的控制中发送。

3.1.2.11.8 User Property

38（0x26）,字节，用户属性标识，

用户属性可出现多次以代表多个键值对，可包含多次。

CONNECT包中的用户属性可用于客户端到服务端的发送连接相关的属性

3.1.2.11.9 Authentication Method

21（0x15）,字节，授权方法标识，后接UTF-8编码字符串，其包含授权方法名称用做扩展授权，协议只可包含不超过一次，缺省不执行授权。

客户端在CONNECT中设置授权方法后，客户端未接收到CONNACK包前，除AUTH或DISCONNECT包不可发送其他包。

3.1.2.11.10 Authentication Data

22（0x16），字节， 授权数据标识，后接包含授权数据的2进制数据，如授权方法不可包含授权数据，协议中只可包含不超过一次。

3.1.3 CONNECT Payload（连接负荷）

连接控制包的负荷包括多个长度预定义的域，其是否包含取决于可变头标记，这些域必须按如下顺序存在，

1. client indetifer,
2. will properti3es,
3. will topic,
4. will payload, u
5. ser name ,
6. password.

3.1.3.1 Client Identifier (ClientID) 客户ID

客户ID作为服务端识别客户端的唯一标识，连接到服务端的每个客户端ID必须唯一。客户端ID需被用于客户端、服务端间识别他们所保持的相关MQTT会话状态。

• 客户端ID必须作为连接控制包负荷的第一个域出现。
• 客户端ID需为UTF-8编码字符串。

• 服务端必须可允许客户端ID为长度1-23字节的UTF-8编码字节，且只包含字符。

  “0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ”

• 服务端如支持长度为0 的客户端ID,服务端需作为特殊情况处理并给客户端分配一个唯一客户端ID,同时必须在CONNACK包中返回客户端ID。

• 如服务端拒绝响应客服端，它可在CONNACK返回消息码（0x85）

3.1.3.2 Will Properties

• 遗愿标记置1时， 负荷数据的下一个域为遗愿属性。
• 遗愿属性与定义了遗愿消息发布时的应用消息属性，同花顺定义了何时发布遗愿消息。
• 遗愿属性包括属性长度和属性内容。

3.1.3.2.1 Property Length

可变字节整数

3.1.3.2.2 Will Delay Interval

• 24(0x18), 1字节，遗愿延时间隔，后接4字节长度整数代表遗愿延时长度，单位s.
• 协议只可包含不多于一次，缺省默认为0，即遗愿消息发布无延时。
• 服务端延时发送客户端的遗愿消息直至遗愿延迟时间到或者会话结束，二者满足其一即可。
• 如果会话在遗愿延时时间到之前，新的网络连接建立，服务端则不发送遗愿消息。
• 当网络临时断开，但客户端成功重连且在遗愿消息发布延续对话，即可避免发布遗愿消息。
• 当客户端连接到服务端的网络连接与已有网络连接的客户ID重复，除非新连接指定clean start且遗愿延时大于0，现有连接发送遗愿消息。
• 如果遗愿延时为0，关于现有网络连接是发送遗愿消息，同时clean start置1，遗愿消息在会话结束前发送。

3.1.3.2.3 Payload Format Indicator

负荷格式标识， 1（0x1）,1字节，后接负荷格式标识值：

• 0，标识遗愿消息未无格式字节，即等于无负荷格式标识。
• 1， 标识遗愿小时为UTF-8编码字符数据，负荷中的UTF-8数据应为RFC 3629 定义的UTF-8格式
• 协议包含多于一次的数据标识，

3.1.3.2.4 Message Expiry Interval

• 2（0x2）, 1字节，消息超时间隔，后接4字节整数代表间隔时间，单位s,协议只可包含不多于一次。
• 4字节长度整数代表遗愿消息的生命周期时间，同时作为服务端发送遗愿消息的发布超时时间。
• 缺省，则服务端发布遗愿消息无超时时间。

3.1.3.2.5 Content Type

• 3（0x3）, 内容类型标识，后接UTF-8编码字符串来描述遗愿消息内容。协议中只可包含不多于一次。
• 内容类型有发送和接收者定义

3.1.3.2.6 Response Topic

• 8（0x8）, 响应话题，后接UTF-8 编码字符串，用作响应消息的话题名称，协议只可包含不多于一次。

3.1.3.2.7 Correlation Data

• 9(0x9), 1字节，相关数据标识，后接二进制数，
• 关联数据被请求消息的发送者用于识别对应的响应，协议只可包含不多于一次，缺省，无相关数据。

3.1.3.2.8 User Property

3.1.3.3 Will Topic

遗愿标记置1，负荷数据的下一个标题，UTF-8编码字符串。

3.1.3.4 Will Payload

如遗愿标志置1， 遗愿负荷为负荷数据的下一个域，遗愿负荷定义了将发布的遗愿话题负荷应用消息，

二进制数。

3.1.3.5 User Name

用户名标记置1， 负荷的下一个域为用户名，UTF-8编码字符串，用于服务器授权

3.1.3.6 Password

如密码标记置，负荷的下一与为密码，密码为二进制数据，尽管该域定义为密码，但可别用于加载验证信息。。

3.1.4 CONNECT Actions

服务端在同一个TCP端口支持多个协议，服务端通过如下方式验证其是否接收的为MQTT V5.0 协议:

1. 服务端在一定时间内没有接收到CONNECT包，服务端应该端口网络连接。
2. 服务端验证接收到的CONNECT包格式OK，否则关闭网络。服务端关闭网络前，可发送一个消息码（0x80）的CONNACK包。
3. 服务可检测CONNECT包的内容是否满足进一步限制且应执行授权和授权验证，如果失败，需关闭网络连接。服务端关闭网络前，可发送一个消息码（0x80）的CONNACK包。

如果验证程工，服务端需执行如下步骤:

1. 如果客户端ID与已连接的客服端重复，服务器发送消息码（0x8E）的DISCONNECT包给当前客户端，

同时关闭当前客户端的网络连接。如果当前客户端有遗愿消息，则发布遗愿消息。

1. 服务端必须执行clean start流程
2. 服务必须以消息码（0x00）CONNACK包确认CONNECT包。
3. 如服务端被用于处理任何商业关键数据，应进行授权检查，如授权通过，服务端发送消息码(0x00)的CONNACK包，如失败则建议不发送任何CONNACK包，因为其可导致密码猜测攻击。
4. 启动消息传输及保持生命周期关注。

客服端允许在发送CONNECT包后立即发送更多的MQTT控制包。客服端不需要等待服务端的CONNACK包到达。如服务端拒绝CONNECT，它不会处理CONNECT包后接受的除ATUTH包外的任何客户端数据

客服端通常等待CONNACK包，然而客户端在接收到CONNACK前，可自由发送MQTT控制包，它可简化客服端实现且无需检测连接状态。

3.2 CONNACK - connect acknowledgement

CONNACK控制包： 服务端发给接收到的客户端CONNECT包响应。

服务在发送任何AUTH前，必须发送 消息码0x00的CONNACK包。

同一网络连接不可发送多于一个CONNACK包，这个软件如何保证？

客户端未在一定时间内接收到CONNACK包，客户端需关闭网络连接**。**

3.2.1 CONNACK Fixed Header

3.2.2 CONNACK Variable Header

CONANCK可变头，包括如下域: 连接确认标记，CONNECT x消息码，

3.2.2.1 Connect Acknowledge Flags

位置： byte 1; Bits7-1默认为0， bit0:会话存在标记

3.2.2.1.1 Session Present

会话存在标记提示客户端，服务端使用的会话状态是否来自此客户端ID的先前的连接，

进而使得客户端和服务端保持会话状态的持续观察。

服务端接收到clean start置1的连接，必须在CONNACK包中 session present为0，同时消息码设置为0x00.

服务接收到Clean start置1的连接，同时服务端保持有该客户端ID的会话状态，它需在CONNACK中置1 session present, 否则置0， 两种情况下CONNACK 包中的消息只0x00。

如果客服端接收到的服务端会话存在值与预期不一致， 客户端做如下处理：

1. 接收到session present置1，但客户端未有会话状态，客户端关闭网络连接。如客户端希望重启新的会话，可使用clean start 置1重连。
2. 如果客户保有会话状态，但接收到session present置0， 客户端丢弃其会话状态，同时保持网络连接。
3. 服务发送包含非0值消息码CONNACK包时，需置0 session presetn 标记。

3.2.2.2 Connect Reason Code

3.2.2.3 CONNACK Properties

3.2.2.3.1 Property Length

CONNACK的属性长度，可变字节长度

3.2.2.3.2 Session Expiry Interval

17（0x11）,字节，会话超时间隔，后接4字节整数代表会话超时时间，单位是，协议只可包含不多一次。

缺省则使用CONNECT的值。

服务端使用这个属性告知客户端，其使用CONNACK的该值而非客户端发送。

3.2.2.3.3 Receive Maximum

33（0x21）,字节， 接收最大字节，后接2字节代表最大接收值，协议不可包含多于一次或值为0，否则为错误。

服务端使用该值限制其可对该客户端并处理的QoS1和QoS2发布数量，不限制QoS 0.，缺省默认65535.

3.2.2.3.4 Maximum QoS

36（0x24）,字节，QoS最大值标识， 后接一个字节， 值为0或1，协议不可包含多余一次且值不可为0，1外的值，缺省默认2.

1. 如果服务不支持QoS1和QoS2发布包，它必须在CONNACK中指定其支持的最大QoS.
2. 服务端不支持QoS1和QoS2发布包，它必须仍然可以接收QoS为0,1,2的定阅请求。
3. 客户端接收到服务端的QoS最大值，它不可发送超过最大QoS等级的发布包。
4. 服务端接收到定义等级超过其最大QoS等级值，其可断开连接并返回消息码(0x9b）.
5. 服务接收的CONNECT包包含的遗愿QoS超过其能力，它必须拒绝连接，同时返回消息码0x9b的CONNACK包且关闭网络连接。

3.2.2.3.5 Retain Available

37（0x25）,字节，保存可用标识，后接1字节域，这个字节表明服务端是否支持消息保持。

0：不支持消息保持，1：支持消息保持，缺省默认支持保持消息。协议只可包含不多于一次或取值不为0,1，否则为协议错误。

1. 客服端接收到 服务端的保持可用置0，它的发布包不可置1RETAIN标记，服务端接收到该包则认为协议错误，服务端应返回消息码0x9a的DISCONNECT。

3.2.2.3.6 Maximum Packet Size

39(0x27)，字节，最大包大小标识，后接4字节整数代表可接收的最大包大小，缺省协议无此限制，仅由可变头长度和协议头大小决定。

协议不可包含多余1次或值为0，否则协议错误。

1. 包大小为MQTT控制包全部字节数，服务端使用该值告知客户的包大小不可超过该限制。
2. 客户端不可发送超过最大包大小的包，如服务端接收到超过下周的包，为协议错误，服务端返回DISCONNECT（消息码:0x95）

3.2.2.3.7 Assigned Client Identifier

18(0X12), 字节，指定客户端ID标识，后接UTF-8字符串代表指定的客户端ID，协议包含多于一个为协议错误。

1. 当接收的CONNECT包中客户ID为0是，服务分配客户端ID。
2. 如客户端使用0字节长度客户端ID连接，服务端在CONNACK响应中必须包含一个分配的客户端ID。该客户端ID必须为一个未被该服务器其他会话使用的新的客户端ID

3.2.2.3.8 Topic Alias Maximum

34（0x22）,字节，话题别名最大值，后接2字节整数，代表话题别名最大值。

包含多于一次话题别名最大值为协议错误，缺省默认为0.

1. 该值用于标识服务端可接受的客户端发送的话题别名最大值，服务端使用它限制连接可保持的话题别名最大值。
2. 客户端的发布包中发送的话题别名不可超过该值，0标识服务端对该连接不接受任何话题别名，缺省后值为0，客户端不可发送任何话题别名给服务端。

3.2.2.3.8 Topic Alias Maximum

34 (0x22) Byte, Identifier of the Topic Alias Maximum，后接2字节代表货梯别名最大值，包含多于一个为协议错误，缺省默认为0。

• 该值标识服务可接受的客户端发送的话题别名最大值，服务端使用该值限制连接中可保持的话题别名数据。
• 值为0,标识服务端在该连接不接收任何话题别名。

3.2.2.3.9 Reason String

31 (0x1F) Byte Identifier of the Reason String.，后接UTF-8字符串，代表响应的原因。该字符串为明文可读，不需解析。

3.2.2.3.10 User Property

38 (0x26) Byte, Identifier of User Property，后接UTF-8字符串对，用于提供更多信息给客户端，包括诊断信息。当包含此值超过最大包大小限制是，服务端不可发送此属性，可包含多次。

3.2.2.3.11 Wildcard Subscription Available

40 (0x28) Byte, Identifier of Wildcard Subscription Available， 后接1字节域，该字节声明服务端是否支持通配符订阅。

• 值为0， 即不支持通配符订阅， 1： 支持通配符订阅。
• 缺省默认支持通配符订阅。
• 协议包含多次或者值不是0,1，为协议错误。
• 服务接收到包含通配符订阅的订阅包且其不支持通配符订阅，为协议错误，服务端返回消息码为0xA1的DISCONNECT包。

3.2.2.3.12 Subscription Identifiers Available

41 (0x29) Byte, 订阅标识可用标识， 后接一字节域，其标识服务端是否支持订阅标识。

• 值为0，不支持订阅标识，1：支持订阅标识，缺省默认支持，
• 协议包含多于一次或者发送值非0,1，为协议错误。

3.2.2.3.13 Shared Subscription Available

42 (0x2A) Byte, 共享订阅可得标识，后接1字节，其代表服务端是否支持共享订阅。

• 0：不支持， 1：支持，缺省默认支持。
• 协议包含多于一次或者发送值非0,1，为协议错误。
• 服务端接收到包含共享订阅的订阅包，但其不支持共享订阅，为协议错误。服务端返回消息码0x9E的DISCONNECT包

3.2.2.3.14 Server Keep Alive

19 (0x13) Byte, 服务端keep alive标识， 后接2字节整数，代表服务端指定keep alive值。

• 服务端在CONNACK包中发送keep alive,客户端必须使用该值替换客户端在CONNECT发送的keep alive值。
• 如果服务端不发送服务端keep alive值，服务端必须使用客户端在CONNECT中设定的值。
• 协议包含多于一次为协议错误。
• keep alive的主要用途为服务端告知客户端，在客服端指定的keep alive到时服务端会断开客户端。

3.2.2.3.15 Response Information

26 (0x1A) Byte, 响应信息标识，后接一个UTF-8编码字符串，用于创建响应话题，

3.2.2.3.16 Server Reference

28 (0x1C) Byte, 服务端参考标识，后接一个UTF-8编码字符串，可被客户端用于标识其他再说会用的服务端，包含多于一次为协议错误。

3.2.2.3.17 Authentication Method

21 (0x15) Byte, 授权方法标识， 后接一个UTF-8编码字符串，包含 授权方法名称，协议保养多于一次为协议错误。

3.2.2.3.18 Authentication Data

22 (0x16) Byte, 授权数据标识， 后接包含授权数据的二进制数据，数据内容有授权方法和已交换的授权数据定义。协议包含多于一次为协议错误。

3.2.3 CONNACK Payload

无