source/include/mqtt_protocol.h

0001 /*
0002 Copyright (c) 2009-2020 Roger Light <roger@atchoo.org>
0003
0004 All rights reserved. This program and the accompanying materials
0005 are made available under the terms of the Eclipse Public License 2.0
0006 and Eclipse Distribution License v1.0 which accompany this distribution.
0007
0008 The Eclipse Public License is available at
0009    https://www.eclipse.org/legal/epl-2.0/
0010 and the Eclipse Distribution License is available at
0011   http://www.eclipse.org/org/documents/edl-v10.php.
0012
0013 SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
0014
0015 Contributors:
0016    Roger Light - initial implementation and documentation.
0017 */
0018
0019 #ifndef MQTT_PROTOCOL_H
0020 #define MQTT_PROTOCOL_H
0021
0022 /*
0023  * File: mqtt_protocol.h
0024  *
0025  * This header contains definitions of MQTT values as defined in the specifications.
0026  */
0027 #define PROTOCOL_NAME_v31 "MQIsdp"
0028 #define PROTOCOL_VERSION_v31 3
0029
0030 #define PROTOCOL_NAME "MQTT"
0031
0032 #define PROTOCOL_VERSION_v311 4
0033 #define PROTOCOL_VERSION_v5 5
0034
0035
0036 /* Message types */
0037 #define CMD_CONNECT 0x10U
0038 #define CMD_CONNACK 0x20U
0039 #define CMD_PUBLISH 0x30U
0040 #define CMD_PUBACK 0x40U
0041 #define CMD_PUBREC 0x50U
0042 #define CMD_PUBREL 0x60U
0043 #define CMD_PUBCOMP 0x70U
0044 #define CMD_SUBSCRIBE 0x80U
0045 #define CMD_SUBACK 0x90U
0046 #define CMD_UNSUBSCRIBE 0xA0U
0047 #define CMD_UNSUBACK 0xB0U
0048 #define CMD_PINGREQ 0xC0U
0049 #define CMD_PINGRESP 0xD0U
0050 #define CMD_DISCONNECT 0xE0U
0051 #define CMD_AUTH 0xF0U
0052
0053 /* Mosquitto only: for distinguishing CONNECT and WILL properties */
0054 #define CMD_WILL 0x100
0055
0056 /* Enum: mqtt311_connack_codes
0057  *
0058  * The CONNACK results for MQTT v3.1.1, and v3.1.
0059  *
0060  * Values:
0061  *  CONNACK_ACCEPTED - 0
0062  *  CONNACK_REFUSED_PROTOCOL_VERSION - 1
0063  *  CONNACK_REFUSED_IDENTIFIER_REJECTED - 2
0064  *  CONNACK_REFUSED_SERVER_UNAVAILABLE - 3
0065  *  CONNACK_REFUSED_BAD_USERNAME_PASSWORD - 4
0066  *  CONNACK_REFUSED_NOT_AUTHORIZED - 5
0067  */
0068 enum mqtt311_connack_codes {
0069     CONNACK_ACCEPTED = 0,
0070     CONNACK_REFUSED_PROTOCOL_VERSION = 1,
0071     CONNACK_REFUSED_IDENTIFIER_REJECTED = 2,
0072     CONNACK_REFUSED_SERVER_UNAVAILABLE = 3,
0073     CONNACK_REFUSED_BAD_USERNAME_PASSWORD = 4,
0074     CONNACK_REFUSED_NOT_AUTHORIZED = 5,
0075 };
0076
0077 /* Enum: mqtt5_return_codes
0078  * The reason codes returned in various MQTT commands.
0079  *
0080  * Values:
0081  *  MQTT_RC_SUCCESS - 0
0082  *  MQTT_RC_NORMAL_DISCONNECTION - 0
0083  *  MQTT_RC_GRANTED_QOS0 - 0
0084  *  MQTT_RC_GRANTED_QOS1 - 1
0085  *  MQTT_RC_GRANTED_QOS2 - 2
0086  *  MQTT_RC_DISCONNECT_WITH_WILL_MSG - 4
0087  *  MQTT_RC_NO_MATCHING_SUBSCRIBERS - 16
0088  *  MQTT_RC_NO_SUBSCRIPTION_EXISTED - 17
0089  *  MQTT_RC_CONTINUE_AUTHENTICATION - 24
0090  *  MQTT_RC_REAUTHENTICATE - 25
0091  *  MQTT_RC_UNSPECIFIED - 128
0092  *  MQTT_RC_MALFORMED_PACKET - 129
0093  *  MQTT_RC_PROTOCOL_ERROR - 130
0094  *  MQTT_RC_IMPLEMENTATION_SPECIFIC - 131
0095  *  MQTT_RC_UNSUPPORTED_PROTOCOL_VERSION - 132
0096  *  MQTT_RC_CLIENTID_NOT_VALID - 133
0097  *  MQTT_RC_BAD_USERNAME_OR_PASSWORD - 134
0098  *  MQTT_RC_NOT_AUTHORIZED - 135
0099  *  MQTT_RC_SERVER_UNAVAILABLE - 136
0100  *  MQTT_RC_SERVER_BUSY - 137
0101  *  MQTT_RC_BANNED - 138
0102  *  MQTT_RC_SERVER_SHUTTING_DOWN - 139
0103  *  MQTT_RC_BAD_AUTHENTICATION_METHOD - 140
0104  *  MQTT_RC_KEEP_ALIVE_TIMEOUT - 141
0105  *  MQTT_RC_SESSION_TAKEN_OVER - 142
0106  *  MQTT_RC_TOPIC_FILTER_INVALID - 143
0107  *  MQTT_RC_TOPIC_NAME_INVALID - 144
0108  *  MQTT_RC_PACKET_ID_IN_USE - 145
0109  *  MQTT_RC_PACKET_ID_NOT_FOUND - 146
0110  *  MQTT_RC_RECEIVE_MAXIMUM_EXCEEDED - 147
0111  *  MQTT_RC_TOPIC_ALIAS_INVALID - 148
0112  *  MQTT_RC_PACKET_TOO_LARGE - 149
0113  *  MQTT_RC_MESSAGE_RATE_TOO_HIGH - 150
0114  *  MQTT_RC_QUOTA_EXCEEDED - 151
0115  *  MQTT_RC_ADMINISTRATIVE_ACTION - 152
0116  *  MQTT_RC_PAYLOAD_FORMAT_INVALID - 153
0117  *  MQTT_RC_RETAIN_NOT_SUPPORTED - 154
0118  *  MQTT_RC_QOS_NOT_SUPPORTED - 155
0119  *  MQTT_RC_USE_ANOTHER_SERVER - 156
0120  *  MQTT_RC_SERVER_MOVED - 157
0121  *  MQTT_RC_SHARED_SUBS_NOT_SUPPORTED - 158
0122  *  MQTT_RC_CONNECTION_RATE_EXCEEDED - 159
0123  *  MQTT_RC_MAXIMUM_CONNECT_TIME - 160
0124  *  MQTT_RC_SUBSCRIPTION_IDS_NOT_SUPPORTED - 161
0125  *  MQTT_RC_WILDCARD_SUBS_NOT_SUPPORTED - 162
0126  */
0127 enum mqtt5_return_codes {
0128     MQTT_RC_SUCCESS = 0,                        /* CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, UNSUBACK, AUTH */
0129     MQTT_RC_NORMAL_DISCONNECTION = 0,           /* DISCONNECT */
0130     MQTT_RC_GRANTED_QOS0 = 0,                   /* SUBACK */
0131     MQTT_RC_GRANTED_QOS1 = 1,                   /* SUBACK */
0132     MQTT_RC_GRANTED_QOS2 = 2,                   /* SUBACK */
0133     MQTT_RC_DISCONNECT_WITH_WILL_MSG = 4,       /* DISCONNECT */
0134     MQTT_RC_NO_MATCHING_SUBSCRIBERS = 16,       /* PUBACK, PUBREC */
0135     MQTT_RC_NO_SUBSCRIPTION_EXISTED = 17,       /* UNSUBACK */
0136     MQTT_RC_CONTINUE_AUTHENTICATION = 24,       /* AUTH */
0137     MQTT_RC_REAUTHENTICATE = 25,                /* AUTH */
0138
0139     MQTT_RC_UNSPECIFIED = 128,                  /* CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT */
0140     MQTT_RC_MALFORMED_PACKET = 129,             /* CONNACK, DISCONNECT */
0141     MQTT_RC_PROTOCOL_ERROR = 130,               /* DISCONNECT */
0142     MQTT_RC_IMPLEMENTATION_SPECIFIC = 131,      /* CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT */
0143     MQTT_RC_UNSUPPORTED_PROTOCOL_VERSION = 132, /* CONNACK */
0144     MQTT_RC_CLIENTID_NOT_VALID = 133,           /* CONNACK */
0145     MQTT_RC_BAD_USERNAME_OR_PASSWORD = 134,     /* CONNACK */
0146     MQTT_RC_NOT_AUTHORIZED = 135,               /* CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT */
0147     MQTT_RC_SERVER_UNAVAILABLE = 136,           /* CONNACK */
0148     MQTT_RC_SERVER_BUSY = 137,                  /* CONNACK, DISCONNECT */
0149     MQTT_RC_BANNED = 138,                       /* CONNACK */
0150     MQTT_RC_SERVER_SHUTTING_DOWN = 139,         /* DISCONNECT */
0151     MQTT_RC_BAD_AUTHENTICATION_METHOD = 140,    /* CONNACK */
0152     MQTT_RC_KEEP_ALIVE_TIMEOUT = 141,           /* DISCONNECT */
0153     MQTT_RC_SESSION_TAKEN_OVER = 142,           /* DISCONNECT */
0154     MQTT_RC_TOPIC_FILTER_INVALID = 143,         /* SUBACK, UNSUBACK, DISCONNECT */
0155     MQTT_RC_TOPIC_NAME_INVALID = 144,           /* CONNACK, PUBACK, PUBREC, DISCONNECT */
0156     MQTT_RC_PACKET_ID_IN_USE = 145,             /* PUBACK, SUBACK, UNSUBACK */
0157     MQTT_RC_PACKET_ID_NOT_FOUND = 146,          /* PUBREL, PUBCOMP */
0158     MQTT_RC_RECEIVE_MAXIMUM_EXCEEDED = 147,     /* DISCONNECT */
0159     MQTT_RC_TOPIC_ALIAS_INVALID = 148,          /* DISCONNECT */
0160     MQTT_RC_PACKET_TOO_LARGE = 149,             /* CONNACK, PUBACK, PUBREC, DISCONNECT */
0161     MQTT_RC_MESSAGE_RATE_TOO_HIGH = 150,        /* DISCONNECT */
0162     MQTT_RC_QUOTA_EXCEEDED = 151,               /* PUBACK, PUBREC, SUBACK, DISCONNECT */
0163     MQTT_RC_ADMINISTRATIVE_ACTION = 152,        /* DISCONNECT */
0164     MQTT_RC_PAYLOAD_FORMAT_INVALID = 153,       /* CONNACK, DISCONNECT */
0165     MQTT_RC_RETAIN_NOT_SUPPORTED = 154,         /* CONNACK, DISCONNECT */
0166     MQTT_RC_QOS_NOT_SUPPORTED = 155,            /* CONNACK, DISCONNECT */
0167     MQTT_RC_USE_ANOTHER_SERVER = 156,           /* CONNACK, DISCONNECT */
0168     MQTT_RC_SERVER_MOVED = 157,                 /* CONNACK, DISCONNECT */
0169     MQTT_RC_SHARED_SUBS_NOT_SUPPORTED = 158,    /* SUBACK, DISCONNECT */
0170     MQTT_RC_CONNECTION_RATE_EXCEEDED = 159,     /* CONNACK, DISCONNECT */
0171     MQTT_RC_MAXIMUM_CONNECT_TIME = 160,         /* DISCONNECT */
0172     MQTT_RC_SUBSCRIPTION_IDS_NOT_SUPPORTED = 161, /* SUBACK, DISCONNECT */
0173     MQTT_RC_WILDCARD_SUBS_NOT_SUPPORTED = 162,  /* SUBACK, DISCONNECT */
0174 };
0175
0176 /* Enum: mqtt5_property
0177  * Options for use with MQTTv5 properties.
0178  * Options:
0179  *
0180  *  MQTT_PROP_PAYLOAD_FORMAT_INDICATOR - property option.
0181  *  MQTT_PROP_MESSAGE_EXPIRY_INTERVAL - property option.
0182  *  MQTT_PROP_CONTENT_TYPE - property option.
0183  *  MQTT_PROP_RESPONSE_TOPIC - property option.
0184  *  MQTT_PROP_CORRELATION_DATA - property option.
0185  *  MQTT_PROP_SUBSCRIPTION_IDENTIFIER - property option.
0186  *  MQTT_PROP_SESSION_EXPIRY_INTERVAL - property option.
0187  *  MQTT_PROP_ASSIGNED_CLIENT_IDENTIFIER - property option.
0188  *  MQTT_PROP_SERVER_KEEP_ALIVE - property option.
0189  *  MQTT_PROP_AUTHENTICATION_METHOD - property option.
0190  *  MQTT_PROP_AUTHENTICATION_DATA - property option.
0191  *  MQTT_PROP_REQUEST_PROBLEM_INFORMATION - property option.
0192  *  MQTT_PROP_WILL_DELAY_INTERVAL - property option.
0193  *  MQTT_PROP_REQUEST_RESPONSE_INFORMATION - property option.
0194  *  MQTT_PROP_RESPONSE_INFORMATION - property option.
0195  *  MQTT_PROP_SERVER_REFERENCE - property option.
0196  *  MQTT_PROP_REASON_STRING - property option.
0197  *  MQTT_PROP_RECEIVE_MAXIMUM - property option.
0198  *  MQTT_PROP_TOPIC_ALIAS_MAXIMUM - property option.
0199  *  MQTT_PROP_TOPIC_ALIAS - property option.
0200  *  MQTT_PROP_MAXIMUM_QOS - property option.
0201  *  MQTT_PROP_RETAIN_AVAILABLE - property option.
0202  *  MQTT_PROP_USER_PROPERTY - property option.
0203  *  MQTT_PROP_MAXIMUM_PACKET_SIZE - property option.
0204  *  MQTT_PROP_WILDCARD_SUB_AVAILABLE - property option.
0205  *  MQTT_PROP_SUBSCRIPTION_ID_AVAILABLE - property option.
0206  *  MQTT_PROP_SHARED_SUB_AVAILABLE - property option.
0207  */
0208 enum mqtt5_property {
0209     MQTT_PROP_PAYLOAD_FORMAT_INDICATOR = 1,     /* Byte :               PUBLISH, Will Properties */
0210     MQTT_PROP_MESSAGE_EXPIRY_INTERVAL = 2,      /* 4 byte int :         PUBLISH, Will Properties */
0211     MQTT_PROP_CONTENT_TYPE = 3,                 /* UTF-8 string :       PUBLISH, Will Properties */
0212     MQTT_PROP_RESPONSE_TOPIC = 8,               /* UTF-8 string :       PUBLISH, Will Properties */
0213     MQTT_PROP_CORRELATION_DATA = 9,             /* Binary Data :        PUBLISH, Will Properties */
0214     MQTT_PROP_SUBSCRIPTION_IDENTIFIER = 11,     /* Variable byte int :  PUBLISH, SUBSCRIBE */
0215     MQTT_PROP_SESSION_EXPIRY_INTERVAL = 17,     /* 4 byte int :         CONNECT, CONNACK, DISCONNECT */
0216     MQTT_PROP_ASSIGNED_CLIENT_IDENTIFIER = 18,  /* UTF-8 string :       CONNACK */
0217     MQTT_PROP_SERVER_KEEP_ALIVE = 19,           /* 2 byte int :         CONNACK */
0218     MQTT_PROP_AUTHENTICATION_METHOD = 21,       /* UTF-8 string :       CONNECT, CONNACK, AUTH */
0219     MQTT_PROP_AUTHENTICATION_DATA = 22,         /* Binary Data :        CONNECT, CONNACK, AUTH */
0220     MQTT_PROP_REQUEST_PROBLEM_INFORMATION = 23, /* Byte :               CONNECT */
0221     MQTT_PROP_WILL_DELAY_INTERVAL = 24,         /* 4 byte int :         Will properties */
0222     MQTT_PROP_REQUEST_RESPONSE_INFORMATION = 25,/* Byte :               CONNECT */
0223     MQTT_PROP_RESPONSE_INFORMATION = 26,        /* UTF-8 string :       CONNACK */
0224     MQTT_PROP_SERVER_REFERENCE = 28,            /* UTF-8 string :       CONNACK, DISCONNECT */
0225     MQTT_PROP_REASON_STRING = 31,               /* UTF-8 string :       All except Will properties */
0226     MQTT_PROP_RECEIVE_MAXIMUM = 33,             /* 2 byte int :         CONNECT, CONNACK */
0227     MQTT_PROP_TOPIC_ALIAS_MAXIMUM = 34,         /* 2 byte int :         CONNECT, CONNACK */
0228     MQTT_PROP_TOPIC_ALIAS = 35,                 /* 2 byte int :         PUBLISH */
0229     MQTT_PROP_MAXIMUM_QOS = 36,                 /* Byte :               CONNACK */
0230     MQTT_PROP_RETAIN_AVAILABLE = 37,            /* Byte :               CONNACK */
0231     MQTT_PROP_USER_PROPERTY = 38,               /* UTF-8 string pair :  All */
0232     MQTT_PROP_MAXIMUM_PACKET_SIZE = 39,         /* 4 byte int :         CONNECT, CONNACK */
0233     MQTT_PROP_WILDCARD_SUB_AVAILABLE = 40,      /* Byte :               CONNACK */
0234     MQTT_PROP_SUBSCRIPTION_ID_AVAILABLE = 41,   /* Byte :               CONNACK */
0235     MQTT_PROP_SHARED_SUB_AVAILABLE = 42,        /* Byte :               CONNACK */
0236 };
0237
0238 enum mqtt5_property_type {
0239     MQTT_PROP_TYPE_BYTE = 1,
0240     MQTT_PROP_TYPE_INT16 = 2,
0241     MQTT_PROP_TYPE_INT32 = 3,
0242     MQTT_PROP_TYPE_VARINT = 4,
0243     MQTT_PROP_TYPE_BINARY = 5,
0244     MQTT_PROP_TYPE_STRING = 6,
0245     MQTT_PROP_TYPE_STRING_PAIR = 7
0246 };
0247
0248 /* Enum: mqtt5_sub_options
0249  * Options for use with MQTTv5 subscriptions.
0250  *
0251  * MQTT_SUB_OPT_NO_LOCAL - with this option set, if this client publishes to
0252  * a topic to which it is subscribed, the broker will not publish the
0253  * message back to the client.
0254  *
0255  * MQTT_SUB_OPT_RETAIN_AS_PUBLISHED - with this option set, messages
0256  * published for this subscription will keep the retain flag as was set by
0257  * the publishing client. The default behaviour without this option set has
0258  * the retain flag indicating whether a message is fresh/stale.
0259  *
0260  * MQTT_SUB_OPT_SEND_RETAIN_ALWAYS - with this option set, pre-existing
0261  * retained messages are sent as soon as the subscription is made, even
0262  * if the subscription already exists. This is the default behaviour, so
0263  * it is not necessary to set this option.
0264  *
0265  * MQTT_SUB_OPT_SEND_RETAIN_NEW - with this option set, pre-existing retained
0266  * messages for this subscription will be sent when the subscription is made,
0267  * but only if the subscription does not already exist.
0268  *
0269  * MQTT_SUB_OPT_SEND_RETAIN_NEVER - with this option set, pre-existing
0270  * retained messages will never be sent for this subscription.
0271  */
0272 enum mqtt5_sub_options {
0273     MQTT_SUB_OPT_NO_LOCAL = 0x04,
0274     MQTT_SUB_OPT_RETAIN_AS_PUBLISHED = 0x08,
0275     MQTT_SUB_OPT_SEND_RETAIN_ALWAYS = 0x00,
0276     MQTT_SUB_OPT_SEND_RETAIN_NEW = 0x10,
0277     MQTT_SUB_OPT_SEND_RETAIN_NEVER = 0x20,
0278 };
0279
0280 #define MQTT_MAX_PAYLOAD 268435455U
0281
0282 #endif