1 /******************************************************************************* 2 * Copyright (c) 2017, 2020 IBM Corp. and others 3 * 4 * All rights reserved. This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License v2.0 6 * and Eclipse Distribution License v1.0 which accompany this distribution. 7 * 8 * The Eclipse Public License is available at 9 * https://www.eclipse.org/legal/epl-2.0/ 10 * and the Eclipse Distribution License is available at 11 * http://www.eclipse.org/org/documents/edl-v10.php. 12 * 13 * Contributors: 14 * Ian Craggs - initial API and implementation and/or initial documentation 15 *******************************************************************************/ 16 17 #if !defined(MQTTPROPERTIES_H) 18 #define MQTTPROPERTIES_H 19 20 #include "MQTTExportDeclarations.h" 21 22 #define MQTT_INVALID_PROPERTY_ID -2 23 24 /** The one byte MQTT V5 property indicator */ 25 enum MQTTPropertyCodes { 26 MQTTPROPERTY_CODE_PAYLOAD_FORMAT_INDICATOR = 1, /**< The value is 1 */ 27 MQTTPROPERTY_CODE_MESSAGE_EXPIRY_INTERVAL = 2, /**< The value is 2 */ 28 MQTTPROPERTY_CODE_CONTENT_TYPE = 3, /**< The value is 3 */ 29 MQTTPROPERTY_CODE_RESPONSE_TOPIC = 8, /**< The value is 8 */ 30 MQTTPROPERTY_CODE_CORRELATION_DATA = 9, /**< The value is 9 */ 31 MQTTPROPERTY_CODE_SUBSCRIPTION_IDENTIFIER = 11, /**< The value is 11 */ 32 MQTTPROPERTY_CODE_SESSION_EXPIRY_INTERVAL = 17, /**< The value is 17 */ 33 MQTTPROPERTY_CODE_ASSIGNED_CLIENT_IDENTIFER = 18,/**< The value is 18 */ 34 MQTTPROPERTY_CODE_SERVER_KEEP_ALIVE = 19, /**< The value is 19 */ 35 MQTTPROPERTY_CODE_AUTHENTICATION_METHOD = 21, /**< The value is 21 */ 36 MQTTPROPERTY_CODE_AUTHENTICATION_DATA = 22, /**< The value is 22 */ 37 MQTTPROPERTY_CODE_REQUEST_PROBLEM_INFORMATION = 23,/**< The value is 23 */ 38 MQTTPROPERTY_CODE_WILL_DELAY_INTERVAL = 24, /**< The value is 24 */ 39 MQTTPROPERTY_CODE_REQUEST_RESPONSE_INFORMATION = 25,/**< The value is 25 */ 40 MQTTPROPERTY_CODE_RESPONSE_INFORMATION = 26, /**< The value is 26 */ 41 MQTTPROPERTY_CODE_SERVER_REFERENCE = 28, /**< The value is 28 */ 42 MQTTPROPERTY_CODE_REASON_STRING = 31, /**< The value is 31 */ 43 MQTTPROPERTY_CODE_RECEIVE_MAXIMUM = 33, /**< The value is 33*/ 44 MQTTPROPERTY_CODE_TOPIC_ALIAS_MAXIMUM = 34, /**< The value is 34 */ 45 MQTTPROPERTY_CODE_TOPIC_ALIAS = 35, /**< The value is 35 */ 46 MQTTPROPERTY_CODE_MAXIMUM_QOS = 36, /**< The value is 36 */ 47 MQTTPROPERTY_CODE_RETAIN_AVAILABLE = 37, /**< The value is 37 */ 48 MQTTPROPERTY_CODE_USER_PROPERTY = 38, /**< The value is 38 */ 49 MQTTPROPERTY_CODE_MAXIMUM_PACKET_SIZE = 39, /**< The value is 39 */ 50 MQTTPROPERTY_CODE_WILDCARD_SUBSCRIPTION_AVAILABLE = 40,/**< The value is 40 */ 51 MQTTPROPERTY_CODE_SUBSCRIPTION_IDENTIFIERS_AVAILABLE = 41,/**< The value is 41 */ 52 MQTTPROPERTY_CODE_SHARED_SUBSCRIPTION_AVAILABLE = 42/**< The value is 241 */ 53 }; 54 55 /** 56 * Returns a printable string description of an MQTT V5 property code. 57 * @param value an MQTT V5 property code. 58 * @return the printable string description of the input property code. 59 * NULL if the code was not found. 60 */ 61 LIBMQTT_API const char* MQTTPropertyName(enum MQTTPropertyCodes value); 62 63 /** The one byte MQTT V5 property type */ 64 enum MQTTPropertyTypes { 65 MQTTPROPERTY_TYPE_BYTE, 66 MQTTPROPERTY_TYPE_TWO_BYTE_INTEGER, 67 MQTTPROPERTY_TYPE_FOUR_BYTE_INTEGER, 68 MQTTPROPERTY_TYPE_VARIABLE_BYTE_INTEGER, 69 MQTTPROPERTY_TYPE_BINARY_DATA, 70 MQTTPROPERTY_TYPE_UTF_8_ENCODED_STRING, 71 MQTTPROPERTY_TYPE_UTF_8_STRING_PAIR 72 }; 73 74 /** 75 * Returns the MQTT V5 type code of an MQTT V5 property. 76 * @param value an MQTT V5 property code. 77 * @return the MQTT V5 type code of the input property. -1 if the code was not found. 78 */ 79 LIBMQTT_API int MQTTProperty_getType(enum MQTTPropertyCodes value); 80 81 /** 82 * The data for a length delimited string 83 */ 84 typedef struct 85 { 86 int len; /**< the length of the string */ 87 char* data; /**< pointer to the string data */ 88 } MQTTLenString; 89 90 91 /** 92 * Structure to hold an MQTT version 5 property of any type 93 */ 94 typedef struct 95 { 96 enum MQTTPropertyCodes identifier; /**< The MQTT V5 property id. A multi-byte integer. */ 97 /** The value of the property, as a union of the different possible types. */ 98 union { 99 unsigned char byte; /**< holds the value of a byte property type */ 100 unsigned short integer2; /**< holds the value of a 2 byte integer property type */ 101 unsigned int integer4; /**< holds the value of a 4 byte integer property type */ 102 struct { 103 MQTTLenString data; /**< The value of a string property, or the name of a user property. */ 104 MQTTLenString value; /**< The value of a user property. */ 105 }; 106 } value; 107 } MQTTProperty; 108 109 /** 110 * MQTT version 5 property list 111 */ 112 typedef struct MQTTProperties 113 { 114 int count; /**< number of property entries in the array */ 115 int max_count; /**< max number of properties that the currently allocated array can store */ 116 int length; /**< mbi: byte length of all properties */ 117 MQTTProperty *array; /**< array of properties */ 118 } MQTTProperties; 119 120 #define MQTTProperties_initializer {0, 0, 0, NULL} 121 122 /** 123 * Returns the length of the properties structure when serialized ready for network transmission. 124 * @param props an MQTT V5 property structure. 125 * @return the length in bytes of the properties when serialized. 126 */ 127 int MQTTProperties_len(MQTTProperties* props); 128 129 /** 130 * Add a property pointer to the property array. There is no memory allocation. 131 * @param props The property list to add the property to. 132 * @param prop The property to add to the list. 133 * @return 0 on success, -1 on failure. 134 */ 135 LIBMQTT_API int MQTTProperties_add(MQTTProperties* props, const MQTTProperty* prop); 136 137 /** 138 * Serialize the given property list to a character buffer, e.g. for writing to the network. 139 * @param pptr pointer to the buffer - move the pointer as we add data 140 * @param properties pointer to the property list, can be NULL 141 * @return whether the write succeeded or not: number of bytes written, or < 0 on failure. 142 */ 143 int MQTTProperties_write(char** pptr, const MQTTProperties* properties); 144 145 /** 146 * Reads a property list from a character buffer into an array. 147 * @param properties pointer to the property list to be filled. Should be initalized but empty. 148 * @param pptr pointer to the character buffer. 149 * @param enddata pointer to the end of the character buffer so we don't read beyond. 150 * @return 1 if the properties were read successfully. 151 */ 152 int MQTTProperties_read(MQTTProperties* properties, char** pptr, char* enddata); 153 154 /** 155 * Free all memory allocated to the property list, including any to individual properties. 156 * @param properties pointer to the property list. 157 */ 158 LIBMQTT_API void MQTTProperties_free(MQTTProperties* properties); 159 160 /** 161 * Copy the contents of a property list, allocating additional memory if needed. 162 * @param props pointer to the property list. 163 * @return the duplicated property list. 164 */ 165 LIBMQTT_API MQTTProperties MQTTProperties_copy(const MQTTProperties* props); 166 167 /** 168 * Checks if property list contains a specific property. 169 * @param props pointer to the property list. 170 * @param propid the property id to check for. 171 * @return 1 if found, 0 if not. 172 */ 173 LIBMQTT_API int MQTTProperties_hasProperty(MQTTProperties *props, enum MQTTPropertyCodes propid); 174 175 /** 176 * Returns the number of instances of a property id. Most properties can exist only once. 177 * User properties and subscription ids can exist more than once. 178 * @param props pointer to the property list. 179 * @param propid the property id to check for. 180 * @return the number of times found. Can be 0. 181 */ 182 LIBMQTT_API int MQTTProperties_propertyCount(MQTTProperties *props, enum MQTTPropertyCodes propid); 183 184 /** 185 * Returns the integer value of a specific property. The property given must be a numeric type. 186 * @param props pointer to the property list. 187 * @param propid the property id to check for. 188 * @return the integer value of the property. -9999999 on failure. 189 */ 190 LIBMQTT_API int MQTTProperties_getNumericValue(MQTTProperties *props, enum MQTTPropertyCodes propid); 191 192 /** 193 * Returns the integer value of a specific property when it's not the only instance. 194 * The property given must be a numeric type. 195 * @param props pointer to the property list. 196 * @param propid the property id to check for. 197 * @param index the instance number, starting at 0. 198 * @return the integer value of the property. -9999999 on failure. 199 */ 200 LIBMQTT_API int MQTTProperties_getNumericValueAt(MQTTProperties *props, enum MQTTPropertyCodes propid, int index); 201 202 /** 203 * Returns a pointer to the property structure for a specific property. 204 * @param props pointer to the property list. 205 * @param propid the property id to check for. 206 * @return the pointer to the property structure if found. NULL if not found. 207 */ 208 LIBMQTT_API MQTTProperty* MQTTProperties_getProperty(MQTTProperties *props, enum MQTTPropertyCodes propid); 209 210 /** 211 * Returns a pointer to the property structure for a specific property when it's not the only instance. 212 * @param props pointer to the property list. 213 * @param propid the property id to check for. 214 * @param index the instance number, starting at 0. 215 * @return the pointer to the property structure if found. NULL if not found. 216 */ 217 LIBMQTT_API MQTTProperty* MQTTProperties_getPropertyAt(MQTTProperties *props, enum MQTTPropertyCodes propid, int index); 218 219 #endif /* MQTTPROPERTIES_H */ 220