From d9a34fbb3a9238332495ff8587f25dd2fccd13e1 Mon Sep 17 00:00:00 2001 From: "Roger A. Light" Date: Mon, 11 Jan 2021 10:05:34 +0000 Subject: [PATCH] Improve documentation around the `_v5()` and non-v5 functions. For example `mosquitto_publish()` and `mosquitto_publish_v5(). --- ChangeLog.txt | 4 ++ include/mosquitto.h | 104 +++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 101 insertions(+), 7 deletions(-) diff --git a/ChangeLog.txt b/ChangeLog.txt index 1b296c520d..c5f7c6b2bb 100644 --- a/ChangeLog.txt +++ b/ChangeLog.txt @@ -13,6 +13,10 @@ Broker: before a role that was attached to the group or client is deleted. Closes #1998. +Client library: +- Improve documentation around the `_v5()` and non-v5 functions, e.g. + `mosquitto_publish()` and `mosquitto_publish_v5(). + Build: - `install` Makefile target should depend on `all`, not `mosquitto`, to ensure that man pages are always built. Closes #1989. diff --git a/include/mosquitto.h b/include/mosquitto.h index b2c15cc6fb..d6209e9bb0 100644 --- a/include/mosquitto.h +++ b/include/mosquitto.h @@ -340,6 +340,9 @@ libmosq_EXPORT int mosquitto_reinitialise(struct mosquitto *mosq, const char *id * Configure will information for a mosquitto instance. By default, clients do * not have a will. This must be called before calling . * + * It is valid to use this function for clients using all MQTT protocol versions. + * If you need to set MQTT v5 Will properties, use instead. + * * Parameters: * mosq - a valid mosquitto instance. * topic - the topic on which to publish the will. @@ -367,6 +370,14 @@ libmosq_EXPORT int mosquitto_will_set(struct mosquitto *mosq, const char *topic, * properties. By default, clients do not have a will. This must be called * before calling . * + * 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. + * + * Set your client to use MQTT v5 immediately after it is created: + * + * mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5); + * * Parameters: * mosq - a valid mosquitto instance. * topic - the topic on which to publish the will. @@ -450,6 +461,10 @@ libmosq_EXPORT int mosquitto_username_pw_set(struct mosquitto *mosq, const char * * Connect to an MQTT broker. * + * It is valid to use this function for clients using all MQTT protocol versions. + * If you need to set MQTT v5 CONNECT properties, use + * instead. + * * Parameters: * mosq - a valid mosquitto instance. * host - the hostname or ip address of the broker to connect to. @@ -517,6 +532,14 @@ libmosq_EXPORT int mosquitto_connect_bind(struct mosquitto *mosq, const char *ho * properties, then attach them to this publish. Properties need freeing with * . * + * 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. + * + * Set your client to use MQTT v5 immediately after it is created: + * + * mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5); + * * Parameters: * mosq - a valid mosquitto instance. * host - the hostname or ip address of the broker to connect to. @@ -716,6 +739,10 @@ libmosq_EXPORT int mosquitto_reconnect_async(struct mosquitto *mosq); * * Disconnect from the broker. * + * It is valid to use this function for clients using all MQTT protocol versions. + * If you need to set MQTT v5 DISCONNECT properties, use + * instead. + * * Parameters: * mosq - a valid mosquitto instance. * @@ -735,6 +762,14 @@ libmosq_EXPORT int mosquitto_disconnect(struct mosquitto *mosq); * properties, then attach them to this publish. Properties need freeing with * . * + * 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. + * + * Set your client to use MQTT v5 immediately after it is created: + * + * mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5); + * * Parameters: * mosq - a valid mosquitto instance. * reason_code - the disconnect reason code. @@ -760,6 +795,10 @@ libmosq_EXPORT int mosquitto_disconnect_v5(struct mosquitto *mosq, int reason_co * * Publish a message on a given topic. * + * It is valid to use this function for clients using all MQTT protocol versions. + * If you need to set MQTT v5 PUBLISH properties, use + * instead. + * * Parameters: * mosq - a valid mosquitto instance. * mid - pointer to an int. If not NULL, the function will set this @@ -807,7 +846,13 @@ libmosq_EXPORT int mosquitto_publish(struct mosquitto *mosq, int *mid, const cha * properties, then attach them to this publish. Properties need freeing with * . * - * Requires the mosquitto instance to be connected with MQTT 5. + * 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. + * + * Set your client to use MQTT v5 immediately after it is created: + * + * mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5); * * Parameters: * mosq - a valid mosquitto instance. @@ -860,6 +905,10 @@ libmosq_EXPORT int mosquitto_publish_v5( * * Subscribe to a topic. * + * It is valid to use this function for clients using all MQTT protocol versions. + * If you need to set MQTT v5 SUBSCRIBE properties, use + * instead. + * * Parameters: * mosq - a valid mosquitto instance. * mid - a pointer to an int. If not NULL, the function will set this to @@ -889,8 +938,13 @@ libmosq_EXPORT int mosquitto_subscribe(struct mosquitto *mosq, int *mid, const c * properties, then attach them to this publish. Properties need freeing with * . * - * Requires the mosquitto instance to be connected with MQTT 5. + * 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. * + * Set your client to use MQTT v5 immediately after it is created: + * + * mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5); * * Parameters: * mosq - a valid mosquitto instance. @@ -981,10 +1035,22 @@ libmosq_EXPORT int mosquitto_unsubscribe(struct mosquitto *mosq, int *mid, const * * Unsubscribe from a topic, with attached MQTT properties. * + * It is valid to use this function for clients using all MQTT protocol versions. + * If you need to set MQTT v5 UNSUBSCRIBE properties, use + * instead. + * * Use e.g. and similar to create a list of * properties, then attach them to this publish. Properties need freeing with * . * + * 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. + * + * Set your client to use MQTT v5 immediately after it is created: + * + * mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5); + * * Parameters: * mosq - a valid mosquitto instance. * mid - a pointer to an int. If not NULL, the function will set this to @@ -1891,6 +1957,10 @@ libmosq_EXPORT void mosquitto_connect_with_flags_callback_set(struct mosquitto * * Set the connect callback. This is called when the broker sends a CONNACK * message in response to a connection. * + * It is valid to set this callback for all MQTT protocol versions. If it is + * used with MQTT clients that use MQTT v3.1.1 or earlier, then the `props` + * argument will always be NULL. + * * Parameters: * mosq - a valid mosquitto instance. * on_connect - a callback function in the following form: @@ -1935,6 +2005,10 @@ libmosq_EXPORT void mosquitto_disconnect_callback_set(struct mosquitto *mosq, vo * Set the disconnect callback. This is called when the broker has received the * DISCONNECT command and has disconnected the client. * + * It is valid to set this callback for all MQTT protocol versions. If it is + * used with MQTT clients that use MQTT v3.1.1 or earlier, then the `props` + * argument will always be NULL. + * * Parameters: * mosq - a valid mosquitto instance. * on_disconnect - a callback function in the following form: @@ -1948,7 +2022,7 @@ libmosq_EXPORT void mosquitto_disconnect_callback_set(struct mosquitto *mosq, vo * indicates that the disconnect is unexpected. * props - list of MQTT 5 properties, or NULL */ -libmosq_EXPORT void mosquitto_disconnect_v5_callback_set(struct mosquitto *mosq, void (*on_disconnect)(struct mosquitto *, void *, int, const mosquitto_property *)); +libmosq_EXPORT void mosquitto_disconnect_v5_callback_set(struct mosquitto *mosq, void (*on_disconnect)(struct mosquitto *, void *, int, const mosquitto_property *props)); /* * Function: mosquitto_publish_callback_set @@ -1976,6 +2050,10 @@ libmosq_EXPORT void mosquitto_publish_callback_set(struct mosquitto *mosq, void * called both if the message is sent successfully, or if the broker responded * with an error, which will be reflected in the reason_code parameter. * + * It is valid to set this callback for all MQTT protocol versions. If it is + * used with MQTT clients that use MQTT v3.1.1 or earlier, then the `props` + * argument will always be NULL. + * * Parameters: * mosq - a valid mosquitto instance. * on_publish - a callback function in the following form: @@ -1988,7 +2066,7 @@ libmosq_EXPORT void mosquitto_publish_callback_set(struct mosquitto *mosq, void * reason_code - the MQTT 5 reason code * props - list of MQTT 5 properties, or NULL */ -libmosq_EXPORT void mosquitto_publish_v5_callback_set(struct mosquitto *mosq, void (*on_publish)(struct mosquitto *, void *, int, int, const mosquitto_property *)); +libmosq_EXPORT void mosquitto_publish_v5_callback_set(struct mosquitto *mosq, void (*on_publish)(struct mosquitto *, void *, int, int, const mosquitto_property *props)); /* * Function: mosquitto_message_callback_set @@ -2019,6 +2097,10 @@ libmosq_EXPORT void mosquitto_message_callback_set(struct mosquitto *mosq, void * Set the message callback. This is called when a message is received from the * broker. * + * It is valid to set this callback for all MQTT protocol versions. If it is + * used with MQTT clients that use MQTT v3.1.1 or earlier, then the `props` + * argument will always be NULL. + * * Parameters: * mosq - a valid mosquitto instance. * on_message - a callback function in the following form: @@ -2035,7 +2117,7 @@ libmosq_EXPORT void mosquitto_message_callback_set(struct mosquitto *mosq, void * See Also: * */ -libmosq_EXPORT void mosquitto_message_v5_callback_set(struct mosquitto *mosq, void (*on_message)(struct mosquitto *, void *, const struct mosquitto_message *, const mosquitto_property *)); +libmosq_EXPORT void mosquitto_message_v5_callback_set(struct mosquitto *mosq, void (*on_message)(struct mosquitto *, void *, const struct mosquitto_message *, const mosquitto_property *props)); /* * Function: mosquitto_subscribe_callback_set @@ -2064,6 +2146,10 @@ libmosq_EXPORT void mosquitto_subscribe_callback_set(struct mosquitto *mosq, voi * Set the subscribe callback. This is called when the broker responds to a * subscription request. * + * It is valid to set this callback for all MQTT protocol versions. If it is + * used with MQTT clients that use MQTT v3.1.1 or earlier, then the `props` + * argument will always be NULL. + * * Parameters: * mosq - a valid mosquitto instance. * on_subscribe - a callback function in the following form: @@ -2078,7 +2164,7 @@ libmosq_EXPORT void mosquitto_subscribe_callback_set(struct mosquitto *mosq, voi * the subscriptions. * props - list of MQTT 5 properties, or NULL */ -libmosq_EXPORT void mosquitto_subscribe_v5_callback_set(struct mosquitto *mosq, void (*on_subscribe)(struct mosquitto *, void *, int, int, const int *, const mosquitto_property *)); +libmosq_EXPORT void mosquitto_subscribe_v5_callback_set(struct mosquitto *mosq, void (*on_subscribe)(struct mosquitto *, void *, int, int, const int *, const mosquitto_property *props)); /* * Function: mosquitto_unsubscribe_callback_set @@ -2104,6 +2190,10 @@ libmosq_EXPORT void mosquitto_unsubscribe_callback_set(struct mosquitto *mosq, v * Set the unsubscribe callback. This is called when the broker responds to a * unsubscription request. * + * It is valid to set this callback for all MQTT protocol versions. If it is + * used with MQTT clients that use MQTT v3.1.1 or earlier, then the `props` + * argument will always be NULL. + * * Parameters: * mosq - a valid mosquitto instance. * on_unsubscribe - a callback function in the following form: @@ -2115,7 +2205,7 @@ libmosq_EXPORT void mosquitto_unsubscribe_callback_set(struct mosquitto *mosq, v * mid - the message id of the unsubscribe message. * props - list of MQTT 5 properties, or NULL */ -libmosq_EXPORT void mosquitto_unsubscribe_v5_callback_set(struct mosquitto *mosq, void (*on_unsubscribe)(struct mosquitto *, void *, int, const mosquitto_property *)); +libmosq_EXPORT void mosquitto_unsubscribe_v5_callback_set(struct mosquitto *mosq, void (*on_unsubscribe)(struct mosquitto *, void *, int, const mosquitto_property *props)); /* * Function: mosquitto_log_callback_set