Document that MOSQ_ERR_NOT_SUPPORTED is returned for more methods.

The documentation was wrong, the properties argument is not ignored.
eclipse-mosquitto · Nov 11, 2024 · 5e0d69a · 5e0d69a
1 parent ba2b98d
commit 5e0d69a
Showing 1 changed file with 18 additions and 12 deletions.
diff --git a/include/mosquitto.h b/include/mosquitto.h
@@ -399,8 +399,7 @@ libmosq_EXPORT int mosquitto_will_set(struct mosquitto *mosq, const char *topic,
  * before calling <mosquitto_connect>.
  *
  * If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument
- * will be applied to the Will. For MQTT v3.1.1 and below, the `properties`
- * argument will be ignored.
+ * will be applied to the Will.
  *
  * Set your client to use MQTT v5 immediately after it is created:
  *
@@ -431,6 +430,8 @@ libmosq_EXPORT int mosquitto_will_set(struct mosquitto *mosq, const char *topic,
  * 	                          using MQTT v5
  * 	MOSQ_ERR_PROTOCOL -       if a property is invalid for use with wills.
  *	MOSQ_ERR_DUPLICATE_PROPERTY - if a property is duplicated where it is forbidden.
+ * 	MOSQ_ERR_NOT_SUPPORTED -  if properties is not NULL and the client is not
+ * 	                          using MQTT v5.
  */
 libmosq_EXPORT int mosquitto_will_set_v5(struct mosquitto *mosq, const char *topic, int payloadlen, const void *payload, int qos, bool retain, mosquitto_property *properties);
 
@@ -562,8 +563,7 @@ libmosq_EXPORT int mosquitto_connect_bind(struct mosquitto *mosq, const char *ho
  * <mosquitto_property_free_all>.
  *
  * If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument
- * will be applied to the CONNECT message. For MQTT v3.1.1 and below, the
- * `properties` argument will be ignored.
+ * will be applied to the CONNECT message.
  *
  * Set your client to use MQTT v5 immediately after it is created:
  *
@@ -594,6 +594,8 @@ libmosq_EXPORT int mosquitto_connect_bind(struct mosquitto *mosq, const char *ho
  *                     Windows.
  *	MOSQ_ERR_DUPLICATE_PROPERTY - if a property is duplicated where it is forbidden.
  *	MOSQ_ERR_PROTOCOL - if any property is invalid for use with CONNECT.
+ * 	MOSQ_ERR_NOT_SUPPORTED -  if properties is not NULL and the client is not
+ * 	                          using MQTT v5.
  *
  * See Also:
  * 	<mosquitto_connect>, <mosquitto_connect_async>, <mosquitto_connect_bind_async>
@@ -795,8 +797,7 @@ libmosq_EXPORT int mosquitto_disconnect(struct mosquitto *mosq);
  * <mosquitto_property_free_all>.
  *
  * If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument
- * will be applied to the DISCONNECT message. For MQTT v3.1.1 and below, the
- * `properties` argument will be ignored.
+ * will be applied to the DISCONNECT message.
  *
  * Set your client to use MQTT v5 immediately after it is created:
  *
@@ -813,6 +814,8 @@ libmosq_EXPORT int mosquitto_disconnect(struct mosquitto *mosq);
  * 	MOSQ_ERR_NO_CONN -  if the client isn't connected to a broker.
  *	MOSQ_ERR_DUPLICATE_PROPERTY - if a property is duplicated where it is forbidden.
  *	MOSQ_ERR_PROTOCOL - if any property is invalid for use with DISCONNECT.
+ * 	MOSQ_ERR_NOT_SUPPORTED -  if properties is not NULL and the client is not
+ * 	                          using MQTT v5.
  */
 libmosq_EXPORT int mosquitto_disconnect_v5(struct mosquitto *mosq, int reason_code, const mosquitto_property *properties);
 
@@ -879,8 +882,7 @@ libmosq_EXPORT int mosquitto_publish(struct mosquitto *mosq, int *mid, const cha
  * <mosquitto_property_free_all>.
  *
  * If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument
- * will be applied to the PUBLISH message. For MQTT v3.1.1 and below, the
- * `properties` argument will be ignored.
+ * will be applied to the PUBLISH message.
  *
  * Set your client to use MQTT v5 immediately after it is created:
  *
@@ -920,6 +922,8 @@ libmosq_EXPORT int mosquitto_publish(struct mosquitto *mosq, int *mid, const cha
  *	                             the broker.
  *	MOSQ_ERR_OVERSIZE_PACKET - if the resulting packet would be larger than
  *	                           supported by the broker.
+ * 	MOSQ_ERR_NOT_SUPPORTED -  if properties is not NULL and the client is not
+ * 	                          using MQTT v5.
  */
 libmosq_EXPORT int mosquitto_publish_v5(
 		struct mosquitto *mosq,
@@ -971,8 +975,7 @@ libmosq_EXPORT int mosquitto_subscribe(struct mosquitto *mosq, int *mid, const c
  * <mosquitto_property_free_all>.
  *
  * If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument
- * will be applied to the PUBLISH message. For MQTT v3.1.1 and below, the
- * `properties` argument will be ignored.
+ * will be applied to the PUBLISH message.
  *
  * Set your client to use MQTT v5 immediately after it is created:
  *
@@ -1000,6 +1003,8 @@ libmosq_EXPORT int mosquitto_subscribe(struct mosquitto *mosq, int *mid, const c
  *	MOSQ_ERR_PROTOCOL - if any property is invalid for use with SUBSCRIBE.
  *	MOSQ_ERR_OVERSIZE_PACKET - if the resulting packet would be larger than
  *	                           supported by the broker.
+ * 	MOSQ_ERR_NOT_SUPPORTED -  if properties is not NULL and the client is not
+ * 	                          using MQTT v5.
  */
 libmosq_EXPORT int mosquitto_subscribe_v5(struct mosquitto *mosq, int *mid, const char *sub, int qos, int options, const mosquitto_property *properties);
 
@@ -1076,8 +1081,7 @@ libmosq_EXPORT int mosquitto_unsubscribe(struct mosquitto *mosq, int *mid, const
  * <mosquitto_property_free_all>.
  *
  * If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument
- * will be applied to the PUBLISH message. For MQTT v3.1.1 and below, the
- * `properties` argument will be ignored.
+ * will be applied to the PUBLISH message.
  *
  * Set your client to use MQTT v5 immediately after it is created:
  *
@@ -1103,6 +1107,8 @@ libmosq_EXPORT int mosquitto_unsubscribe(struct mosquitto *mosq, int *mid, const
  *	MOSQ_ERR_PROTOCOL - if any property is invalid for use with UNSUBSCRIBE.
  *	MOSQ_ERR_OVERSIZE_PACKET - if the resulting packet would be larger than
  *	                           supported by the broker.
+ * 	MOSQ_ERR_NOT_SUPPORTED -  if properties is not NULL and the client is not
+ * 	                          using MQTT v5.
  */
 libmosq_EXPORT int mosquitto_unsubscribe_v5(struct mosquitto *mosq, int *mid, const char *sub, const mosquitto_property *properties);