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