github
/
mosquitto
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve documentation around the `_v5()` and non-v5 functions.

Browse Source 
For example `mosquitto_publish()` and `mosquitto_publish_v5().
pull/1698/head
Roger A. Light 5 years ago
parent c4f4fae5a0
commit d9a34fbb3a
2 changed files with 101 additions and 7 deletions
Show Stats Download Patch File Download Diff File

4
ChangeLog.txt
Unescape Escape View File

@ -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.

104
include/mosquitto.h
Unescape Escape View File

@ -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 <mosquitto_connect>.
*
* It is valid to use this function for clients using all MQTT protocol versions.
* If you need to set MQTT v5 Will properties, use <mosquitto_will_set_v5> 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 <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.
*
* 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 <mosquitto_connect_bind_v5>
* 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
* <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.
*
* 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
* <mosquitto_disconnect_v5> 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
* <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.
*
* 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 <mosquitto_publish_v5>
* 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
* <mosquitto_property_free_all>.
*
* 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 <mosquitto_subscribe_v5>
* 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
* <mosquitto_property_free_all>.
*
* 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
* <mosquitto_unsubscribe_v5> instead.
*
* Use e.g. <mosquitto_property_add_string> and similar to create a list of
* properties, then attach them to this publish. Properties need freeing with
* <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.
*
* 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:
* <mosquitto_message_copy>
*/
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

Write Preview
Loading…
Cancel
Save