220 lines
9.3 KiB
C
220 lines
9.3 KiB
C
/*******************************************************************************
|
|
* Copyright (c) 2017, 2020 IBM Corp. and others
|
|
*
|
|
* All rights reserved. This program and the accompanying materials
|
|
* are made available under the terms of the Eclipse Public License v2.0
|
|
* and Eclipse Distribution License v1.0 which accompany this distribution.
|
|
*
|
|
* The Eclipse Public License is available at
|
|
* https://www.eclipse.org/legal/epl-2.0/
|
|
* and the Eclipse Distribution License is available at
|
|
* http://www.eclipse.org/org/documents/edl-v10.php.
|
|
*
|
|
* Contributors:
|
|
* Ian Craggs - initial API and implementation and/or initial documentation
|
|
*******************************************************************************/
|
|
|
|
#if !defined(MQTTPROPERTIES_H)
|
|
#define MQTTPROPERTIES_H
|
|
|
|
#include "MQTTExportDeclarations.h"
|
|
|
|
#define MQTT_INVALID_PROPERTY_ID -2
|
|
|
|
/** The one byte MQTT V5 property indicator */
|
|
enum MQTTPropertyCodes {
|
|
MQTTPROPERTY_CODE_PAYLOAD_FORMAT_INDICATOR = 1, /**< The value is 1 */
|
|
MQTTPROPERTY_CODE_MESSAGE_EXPIRY_INTERVAL = 2, /**< The value is 2 */
|
|
MQTTPROPERTY_CODE_CONTENT_TYPE = 3, /**< The value is 3 */
|
|
MQTTPROPERTY_CODE_RESPONSE_TOPIC = 8, /**< The value is 8 */
|
|
MQTTPROPERTY_CODE_CORRELATION_DATA = 9, /**< The value is 9 */
|
|
MQTTPROPERTY_CODE_SUBSCRIPTION_IDENTIFIER = 11, /**< The value is 11 */
|
|
MQTTPROPERTY_CODE_SESSION_EXPIRY_INTERVAL = 17, /**< The value is 17 */
|
|
MQTTPROPERTY_CODE_ASSIGNED_CLIENT_IDENTIFER = 18,/**< The value is 18 */
|
|
MQTTPROPERTY_CODE_SERVER_KEEP_ALIVE = 19, /**< The value is 19 */
|
|
MQTTPROPERTY_CODE_AUTHENTICATION_METHOD = 21, /**< The value is 21 */
|
|
MQTTPROPERTY_CODE_AUTHENTICATION_DATA = 22, /**< The value is 22 */
|
|
MQTTPROPERTY_CODE_REQUEST_PROBLEM_INFORMATION = 23,/**< The value is 23 */
|
|
MQTTPROPERTY_CODE_WILL_DELAY_INTERVAL = 24, /**< The value is 24 */
|
|
MQTTPROPERTY_CODE_REQUEST_RESPONSE_INFORMATION = 25,/**< The value is 25 */
|
|
MQTTPROPERTY_CODE_RESPONSE_INFORMATION = 26, /**< The value is 26 */
|
|
MQTTPROPERTY_CODE_SERVER_REFERENCE = 28, /**< The value is 28 */
|
|
MQTTPROPERTY_CODE_REASON_STRING = 31, /**< The value is 31 */
|
|
MQTTPROPERTY_CODE_RECEIVE_MAXIMUM = 33, /**< The value is 33*/
|
|
MQTTPROPERTY_CODE_TOPIC_ALIAS_MAXIMUM = 34, /**< The value is 34 */
|
|
MQTTPROPERTY_CODE_TOPIC_ALIAS = 35, /**< The value is 35 */
|
|
MQTTPROPERTY_CODE_MAXIMUM_QOS = 36, /**< The value is 36 */
|
|
MQTTPROPERTY_CODE_RETAIN_AVAILABLE = 37, /**< The value is 37 */
|
|
MQTTPROPERTY_CODE_USER_PROPERTY = 38, /**< The value is 38 */
|
|
MQTTPROPERTY_CODE_MAXIMUM_PACKET_SIZE = 39, /**< The value is 39 */
|
|
MQTTPROPERTY_CODE_WILDCARD_SUBSCRIPTION_AVAILABLE = 40,/**< The value is 40 */
|
|
MQTTPROPERTY_CODE_SUBSCRIPTION_IDENTIFIERS_AVAILABLE = 41,/**< The value is 41 */
|
|
MQTTPROPERTY_CODE_SHARED_SUBSCRIPTION_AVAILABLE = 42/**< The value is 241 */
|
|
};
|
|
|
|
/**
|
|
* Returns a printable string description of an MQTT V5 property code.
|
|
* @param value an MQTT V5 property code.
|
|
* @return the printable string description of the input property code.
|
|
* NULL if the code was not found.
|
|
*/
|
|
LIBMQTT_API const char* MQTTPropertyName(enum MQTTPropertyCodes value);
|
|
|
|
/** The one byte MQTT V5 property type */
|
|
enum MQTTPropertyTypes {
|
|
MQTTPROPERTY_TYPE_BYTE,
|
|
MQTTPROPERTY_TYPE_TWO_BYTE_INTEGER,
|
|
MQTTPROPERTY_TYPE_FOUR_BYTE_INTEGER,
|
|
MQTTPROPERTY_TYPE_VARIABLE_BYTE_INTEGER,
|
|
MQTTPROPERTY_TYPE_BINARY_DATA,
|
|
MQTTPROPERTY_TYPE_UTF_8_ENCODED_STRING,
|
|
MQTTPROPERTY_TYPE_UTF_8_STRING_PAIR
|
|
};
|
|
|
|
/**
|
|
* Returns the MQTT V5 type code of an MQTT V5 property.
|
|
* @param value an MQTT V5 property code.
|
|
* @return the MQTT V5 type code of the input property. -1 if the code was not found.
|
|
*/
|
|
LIBMQTT_API int MQTTProperty_getType(enum MQTTPropertyCodes value);
|
|
|
|
/**
|
|
* The data for a length delimited string
|
|
*/
|
|
typedef struct
|
|
{
|
|
int len; /**< the length of the string */
|
|
char* data; /**< pointer to the string data */
|
|
} MQTTLenString;
|
|
|
|
|
|
/**
|
|
* Structure to hold an MQTT version 5 property of any type
|
|
*/
|
|
typedef struct
|
|
{
|
|
enum MQTTPropertyCodes identifier; /**< The MQTT V5 property id. A multi-byte integer. */
|
|
/** The value of the property, as a union of the different possible types. */
|
|
union {
|
|
unsigned char byte; /**< holds the value of a byte property type */
|
|
unsigned short integer2; /**< holds the value of a 2 byte integer property type */
|
|
unsigned int integer4; /**< holds the value of a 4 byte integer property type */
|
|
struct {
|
|
MQTTLenString data; /**< The value of a string property, or the name of a user property. */
|
|
MQTTLenString value; /**< The value of a user property. */
|
|
};
|
|
} value;
|
|
} MQTTProperty;
|
|
|
|
/**
|
|
* MQTT version 5 property list
|
|
*/
|
|
typedef struct MQTTProperties
|
|
{
|
|
int count; /**< number of property entries in the array */
|
|
int max_count; /**< max number of properties that the currently allocated array can store */
|
|
int length; /**< mbi: byte length of all properties */
|
|
MQTTProperty *array; /**< array of properties */
|
|
} MQTTProperties;
|
|
|
|
#define MQTTProperties_initializer {0, 0, 0, NULL}
|
|
|
|
/**
|
|
* Returns the length of the properties structure when serialized ready for network transmission.
|
|
* @param props an MQTT V5 property structure.
|
|
* @return the length in bytes of the properties when serialized.
|
|
*/
|
|
int MQTTProperties_len(MQTTProperties* props);
|
|
|
|
/**
|
|
* Add a property pointer to the property array. There is no memory allocation.
|
|
* @param props The property list to add the property to.
|
|
* @param prop The property to add to the list.
|
|
* @return 0 on success, -1 on failure.
|
|
*/
|
|
LIBMQTT_API int MQTTProperties_add(MQTTProperties* props, const MQTTProperty* prop);
|
|
|
|
/**
|
|
* Serialize the given property list to a character buffer, e.g. for writing to the network.
|
|
* @param pptr pointer to the buffer - move the pointer as we add data
|
|
* @param properties pointer to the property list, can be NULL
|
|
* @return whether the write succeeded or not: number of bytes written, or < 0 on failure.
|
|
*/
|
|
int MQTTProperties_write(char** pptr, const MQTTProperties* properties);
|
|
|
|
/**
|
|
* Reads a property list from a character buffer into an array.
|
|
* @param properties pointer to the property list to be filled. Should be initalized but empty.
|
|
* @param pptr pointer to the character buffer.
|
|
* @param enddata pointer to the end of the character buffer so we don't read beyond.
|
|
* @return 1 if the properties were read successfully.
|
|
*/
|
|
int MQTTProperties_read(MQTTProperties* properties, char** pptr, char* enddata);
|
|
|
|
/**
|
|
* Free all memory allocated to the property list, including any to individual properties.
|
|
* @param properties pointer to the property list.
|
|
*/
|
|
LIBMQTT_API void MQTTProperties_free(MQTTProperties* properties);
|
|
|
|
/**
|
|
* Copy the contents of a property list, allocating additional memory if needed.
|
|
* @param props pointer to the property list.
|
|
* @return the duplicated property list.
|
|
*/
|
|
LIBMQTT_API MQTTProperties MQTTProperties_copy(const MQTTProperties* props);
|
|
|
|
/**
|
|
* Checks if property list contains a specific property.
|
|
* @param props pointer to the property list.
|
|
* @param propid the property id to check for.
|
|
* @return 1 if found, 0 if not.
|
|
*/
|
|
LIBMQTT_API int MQTTProperties_hasProperty(MQTTProperties *props, enum MQTTPropertyCodes propid);
|
|
|
|
/**
|
|
* Returns the number of instances of a property id. Most properties can exist only once.
|
|
* User properties and subscription ids can exist more than once.
|
|
* @param props pointer to the property list.
|
|
* @param propid the property id to check for.
|
|
* @return the number of times found. Can be 0.
|
|
*/
|
|
LIBMQTT_API int MQTTProperties_propertyCount(MQTTProperties *props, enum MQTTPropertyCodes propid);
|
|
|
|
/**
|
|
* Returns the integer value of a specific property. The property given must be a numeric type.
|
|
* @param props pointer to the property list.
|
|
* @param propid the property id to check for.
|
|
* @return the integer value of the property. -9999999 on failure.
|
|
*/
|
|
LIBMQTT_API int MQTTProperties_getNumericValue(MQTTProperties *props, enum MQTTPropertyCodes propid);
|
|
|
|
/**
|
|
* Returns the integer value of a specific property when it's not the only instance.
|
|
* The property given must be a numeric type.
|
|
* @param props pointer to the property list.
|
|
* @param propid the property id to check for.
|
|
* @param index the instance number, starting at 0.
|
|
* @return the integer value of the property. -9999999 on failure.
|
|
*/
|
|
LIBMQTT_API int MQTTProperties_getNumericValueAt(MQTTProperties *props, enum MQTTPropertyCodes propid, int index);
|
|
|
|
/**
|
|
* Returns a pointer to the property structure for a specific property.
|
|
* @param props pointer to the property list.
|
|
* @param propid the property id to check for.
|
|
* @return the pointer to the property structure if found. NULL if not found.
|
|
*/
|
|
LIBMQTT_API MQTTProperty* MQTTProperties_getProperty(MQTTProperties *props, enum MQTTPropertyCodes propid);
|
|
|
|
/**
|
|
* Returns a pointer to the property structure for a specific property when it's not the only instance.
|
|
* @param props pointer to the property list.
|
|
* @param propid the property id to check for.
|
|
* @param index the instance number, starting at 0.
|
|
* @return the pointer to the property structure if found. NULL if not found.
|
|
*/
|
|
LIBMQTT_API MQTTProperty* MQTTProperties_getPropertyAt(MQTTProperties *props, enum MQTTPropertyCodes propid, int index);
|
|
|
|
#endif /* MQTTPROPERTIES_H */
|