Improve API documentation.

Fix return code on callback unregister.

include/mosquitto.h

@@ -19,6 +19,13 @@ SPDX-License-Identifier: EPL-2.0 OR EDL-1.0
 #ifndef MOSQUITTO_H
 #define MOSQUITTO_H
 
+/*
+ * File: mosquitto.h
+ *
+ * This header contains functions and definitions for use with libmosquitto, the Mosquitto client library.
+ *
+ * The definitions are also used in Mosquitto broker plugins, and some functions are available to plugins.
+ */
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -3059,8 +3066,8 @@ libmosq_EXPORT void mosquitto_property_free_all(mosquitto_property **properties)
  * Function: mosquitto_property_copy_all
  *
  * Parameters:
- * dest : pointer for new property list
- * src : property list
+ * dest - pointer for new property list
+ * src - property list
  *
  * Returns:
  * MOSQ_ERR_SUCCESS - on successful copy

include/mosquitto_broker.h

@@ -16,6 +16,11 @@ SPDX-License-Identifier: EPL-2.0 OR EDL-1.0
  Roger Light - initial implementation and documentation.
 */
 
+/*
+ * File: mosquitto_broker.h
+ *
+ * This header contains functions for use by plugins.
+ */
 #ifndef MOSQUITTO_BROKER_H
 #define MOSQUITTO_BROKER_H
 
@@ -44,7 +49,7 @@ enum mosquitto_protocol {
 
 /* =========================================================================
  *
- * Register callbacks.
+ * Section: Register callbacks.
  *
  * ========================================================================= */
 
@@ -172,6 +177,31 @@ typedef struct mosquitto_plugin_id_t mosquitto_plugin_id_t;
 
 /*
  * Function: mosquitto_callback_register
+ *
+ * Register a callback for an event.
+ *
+ * Parameters:
+ * identifier - the plugin identifier, as provided by <mosquitto_plugin_init>.
+ * event - the event to register a callback for. Can be one of:
+ * * MOSQ_EVT_RELOAD
+ * * MOSQ_EVT_ACL_CHECK
+ * * MOSQ_EVT_BASIC_AUTH
+ * * MOSQ_EVT_EXT_AUTH_START
+ * * MOSQ_EVT_EXT_AUTH_CONTINUE
+ * * MOSQ_EVT_CONTROL
+ * * MOSQ_EVT_MESSAGE
+ * * MOSQ_EVT_PSK_KEY
+ * * MOSQ_EVT_TICK
+ * * MOSQ_EVT_DISCONNECT
+ * cb_func - the callback function
+ * event_data - event specific data
+ *
+ * Returns:
+ * MOSQ_ERR_SUCCESS - on success
+ * MOSQ_ERR_INVAL - if cb_func is NULL
+ * MOSQ_ERR_NOMEM - on out of memory
+ * MOSQ_ERR_ALREADY_EXISTS - if cb_func has already been registered for this event
+ * MOSQ_ERR_NOT_SUPPORTED - if the event is not supported
  */
 mosq_EXPORT int mosquitto_callback_register(
  mosquitto_plugin_id_t *identifier,
@@ -182,6 +212,30 @@ mosq_EXPORT int mosquitto_callback_register(
 
 /*
  * Function: mosquitto_callback_unregister
+ *
+ * Unregister a previously registered callback function.
+ *
+ * Parameters:
+ * identifier - the plugin identifier, as provided by <mosquitto_plugin_init>.
+ * event - the event to register a callback for. Can be one of:
+ * * MOSQ_EVT_RELOAD
+ * * MOSQ_EVT_ACL_CHECK
+ * * MOSQ_EVT_BASIC_AUTH
+ * * MOSQ_EVT_EXT_AUTH_START
+ * * MOSQ_EVT_EXT_AUTH_CONTINUE
+ * * MOSQ_EVT_CONTROL
+ * * MOSQ_EVT_MESSAGE
+ * * MOSQ_EVT_PSK_KEY
+ * * MOSQ_EVT_TICK
+ * * MOSQ_EVT_DISCONNECT
+ * cb_func - the callback function
+ * event_data - event specific data
+ *
+ * Returns:
+ * MOSQ_ERR_SUCCESS - on success
+ * MOSQ_ERR_INVAL - if cb_func is NULL
+ * MOSQ_ERR_NOT_FOUND - if cb_func was not registered for this event
+ * MOSQ_ERR_NOT_SUPPORTED - if the event is not supported
  */
 mosq_EXPORT int mosquitto_callback_unregister(
  mosquitto_plugin_id_t *identifier,
@@ -192,21 +246,41 @@ mosq_EXPORT int mosquitto_callback_unregister(
 
 /* =========================================================================
  *
- * Memory allocation.
+ * Section: Memory allocation.
  *
  * Use these functions when allocating or freeing memory to have your memory
  * included in the memory tracking on the broker.
  *
  * ========================================================================= */
+
+/*
+ * Function: mosquitto_calloc
+ */
 mosq_EXPORT void *mosquitto_calloc(size_t nmemb, size_t size);
+
+/*
+ * Function: mosquitto_free
+ */
 mosq_EXPORT void mosquitto_free(void *mem);
+
+/*
+ * Function: mosquitto_malloc
+ */
 mosq_EXPORT void *mosquitto_malloc(size_t size);
+
+/*
+ * Function: mosquitto_realloc
+ */
 mosq_EXPORT void *mosquitto_realloc(void *ptr, size_t size);
+
+/*
+ * Function: mosquitto_strdup
+ */
 mosq_EXPORT char *mosquitto_strdup(const char *s);
 
 /* =========================================================================
  *
- * Utility Functions
+ * Section: Utility Functions
  *
  * Use these functions from within your plugin.
  *
@@ -221,13 +295,13 @@ mosq_EXPORT char *mosquitto_strdup(const char *s);
  * Parameters:
  * level - Log message priority. Can currently be one of:
  *
- * MOSQ_LOG_INFO
- * MOSQ_LOG_NOTICE
- * MOSQ_LOG_WARNING
- * MOSQ_LOG_ERR
- * MOSQ_LOG_DEBUG
- * MOSQ_LOG_SUBSCRIBE (not recommended for use by plugins)
- * MOSQ_LOG_UNSUBSCRIBE (not recommended for use by plugins)
+ * * MOSQ_LOG_INFO
+ * * MOSQ_LOG_NOTICE
+ * * MOSQ_LOG_WARNING
+ * * MOSQ_LOG_ERR
+ * * MOSQ_LOG_DEBUG
+ * * MOSQ_LOG_SUBSCRIBE (not recommended for use by plugins)
+ * * MOSQ_LOG_UNSUBSCRIBE (not recommended for use by plugins)
  *
  * These values are defined in mosquitto.h.
  *
@@ -309,9 +383,10 @@ mosq_EXPORT int mosquitto_client_protocol(const struct mosquitto *client);
  *
  * Retrieve the MQTT protocol version with which the client has connected. Can be one of:
  *
- * 3 - for MQTT v3 / v3.1
- * 4 - for MQTT v3.1.1
- * 5 - for MQTT v5
+ * Returns:
+ * 3 - for MQTT v3 / v3.1
+ * 4 - for MQTT v3.1.1
+ * 5 - for MQTT v5
  */
 mosq_EXPORT int mosquitto_client_protocol_version(const struct mosquitto *client);
 
@@ -354,7 +429,7 @@ mosq_EXPORT int mosquitto_set_username(struct mosquitto *client, const char *use
 
 /* =========================================================================
  *
- * Client control
+ * Section: Client control
  *
  * ========================================================================= */
 
@@ -388,7 +463,7 @@ mosq_EXPORT int mosquitto_kick_client_by_username(const char *username, bool wit
 
 /* =========================================================================
  *
- * Publishing functions
+ * Section: Publishing functions
  *
  * ========================================================================= */
 

include/mosquitto_plugin.h

@@ -19,6 +19,12 @@ SPDX-License-Identifier: EPL-2.0 OR EDL-1.0
 #ifndef MOSQUITTO_PLUGIN_H
 #define MOSQUITTO_PLUGIN_H
 
+/*
+ * File: mosquitto_plugin.h
+ *
+ * This header contains function declarations for use when writing a Mosquitto plugin.
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -108,7 +114,7 @@ struct mosquitto_acl_msg {
 
 /* =========================================================================
  *
- * Plugin Functions v5
+ * Section: Plugin Functions v5
  *
  * This is the plugin version 5 interface, which covers authentication, access
  * control, the $CONTROL topic space handling, and message inspection and
@@ -146,13 +152,13 @@ mosq_plugin_EXPORT int mosquitto_plugin_version(int supported_version_count, con
  *
  * Parameters:
  *
- * identifier : This is a pointer to an opaque structure which you must
+ * identifier - This is a pointer to an opaque structure which you must
  * save and use when registering/unregistering callbacks.
- * user_data : The pointer set here will be passed to the other plugin
+ * user_data - The pointer set here will be passed to the other plugin
  * functions. Use to hold connection information for example.
- * opts : Pointer to an array of struct mosquitto_opt, which
+ * opts - Pointer to an array of struct mosquitto_opt, which
  * provides the plugin options defined in the configuration file.
- * opt_count : The number of elements in the opts array.
+ * opt_count - The number of elements in the opts array.
  *
  * Return value:
  * Return 0 on success
@@ -169,10 +175,10 @@ mosq_plugin_EXPORT int mosquitto_plugin_init(mosquitto_plugin_id_t *identifier,
  *
  * Parameters:
  *
- * user_data : The pointer provided in <mosquitto_auth_plugin_init>.
- * opts : Pointer to an array of struct mosquitto_opt, which
+ * user_data - The pointer provided in <mosquitto_plugin_init>.
+ * opts - Pointer to an array of struct mosquitto_opt, which
  * provides the plugin options defined in the configuration file.
- * opt_count : The number of elements in the opts array.
+ * opt_count - The number of elements in the opts array.
  *
  * Return value:
  * Return 0 on success
@@ -184,7 +190,7 @@ mosq_plugin_EXPORT int mosquitto_plugin_cleanup(void *userdata, struct mosquitto
 
 /* =========================================================================
  *
- * Plugin Functions v4
+ * Section: Plugin Functions v4
  *
  * This is the plugin version 4 interface, which is exclusively for
  * authentication and access control, and which is still supported for existing
@@ -213,11 +219,11 @@ mosq_plugin_EXPORT int mosquitto_auth_plugin_version(void);
  *
  * Parameters:
  *
- * user_data : The pointer set here will be passed to the other plugin
+ * user_data - The pointer set here will be passed to the other plugin
  * functions. Use to hold connection information for example.
- * opts : Pointer to an array of struct mosquitto_opt, which
+ * opts - Pointer to an array of struct mosquitto_opt, which
  * provides the plugin options defined in the configuration file.
- * opt_count : The number of elements in the opts array.
+ * opt_count - The number of elements in the opts array.
  *
  * Return value:
  * Return 0 on success
@@ -236,10 +242,10 @@ mosq_plugin_EXPORT int mosquitto_auth_plugin_init(void **user_data, struct mosqu
  *
  * Parameters:
  *
- * user_data : The pointer provided in <mosquitto_auth_plugin_init>.
- * opts : Pointer to an array of struct mosquitto_opt, which
+ * user_data - The pointer provided in <mosquitto_auth_plugin_init>.
+ * opts - Pointer to an array of struct mosquitto_opt, which
  * provides the plugin options defined in the configuration file.
- * opt_count : The number of elements in the opts array.
+ * opt_count - The number of elements in the opts array.
  *
  * Return value:
  * Return 0 on success
@@ -261,11 +267,11 @@ mosq_plugin_EXPORT int mosquitto_auth_plugin_cleanup(void *user_data, struct mos
  *
  * Parameters:
  *
- * user_data : The pointer provided in <mosquitto_auth_plugin_init>.
- * opts : Pointer to an array of struct mosquitto_opt, which
+ * user_data - The pointer provided in <mosquitto_auth_plugin_init>.
+ * opts - Pointer to an array of struct mosquitto_opt, which
  * provides the plugin options defined in the configuration file.
- * opt_count : The number of elements in the opts array.
- * reload : If set to false, this is the first time the function has
+ * opt_count - The number of elements in the opts array.
+ * reload - If set to false, this is the first time the function has
  * been called. If true, the broker has received a signal
  * asking to reload its configuration.
  *
@@ -289,11 +295,11 @@ mosq_plugin_EXPORT int mosquitto_auth_security_init(void *user_data, struct mosq
  *
  * Parameters:
  *
- * user_data : The pointer provided in <mosquitto_auth_plugin_init>.
- * opts : Pointer to an array of struct mosquitto_opt, which
+ * user_data - The pointer provided in <mosquitto_auth_plugin_init>.
+ * opts - Pointer to an array of struct mosquitto_opt, which
  * provides the plugin options defined in the configuration file.
- * opt_count : The number of elements in the opts array.
- * reload : If set to false, this is the first time the function has
+ * opt_count - The number of elements in the opts array.
+ * reload - If set to false, this is the first time the function has
  * been called. If true, the broker has received a signal
  * asking to reload its configuration.
  *
@@ -362,11 +368,11 @@ mosq_plugin_EXPORT int mosquitto_auth_unpwd_check(void *user_data, struct mosqui
  * hexadecimal string with no leading "0x") and copy this string into key.
  *
  * Parameters:
- * user_data : the pointer provided in <mosquitto_auth_plugin_init>.
- * hint : the psk_hint for the listener the client is connecting to.
- * identity : the identity string provided by the client
- * key : a string where the hex PSK should be copied
- * max_key_len : the size of key
+ * user_data - the pointer provided in <mosquitto_auth_plugin_init>.
+ * hint - the psk_hint for the listener the client is connecting to.
+ * identity - the identity string provided by the client
+ * key - a string where the hex PSK should be copied
+ * max_key_len - the size of key
  *
  * Return value:
  * Return 0 on success.
@@ -382,17 +388,17 @@ mosq_plugin_EXPORT int mosquitto_auth_psk_key_get(void *user_data, struct mosqui
  * are making extended authentication checks.
  *
  * Parameters:
- * user_data : the pointer provided in <mosquitto_auth_plugin_init>.
- * method : the authentication method
- * reauth : this is set to false if this is the first authentication attempt
+ * user_data - the pointer provided in <mosquitto_auth_plugin_init>.
+ * method - the authentication method
+ * reauth - this is set to false if this is the first authentication attempt
  * on a connection, set to true if the client is attempting to
  * reauthenticate.
- * data_in : pointer to authentication data, or NULL
- * data_in_len : length of data_in, in bytes
- * data_out : if your plugin wishes to send authentication data back to the
+ * data_in - pointer to authentication data, or NULL
+ * data_in_len - length of data_in, in bytes
+ * data_out - if your plugin wishes to send authentication data back to the
  * client, allocate some memory using malloc or friends and set
  * data_out. The broker will free the memory after use.
- * data_out_len : Set the length of data_out in bytes.
+ * data_out_len - Set the length of data_out in bytes.
  *
  * Return value:
  * Return MOSQ_ERR_SUCCESS if authentication was successful.