Improve API documentation.

Fix return code on callback unregister.

include/mosquitto.h

@@ -19,6 +19,13 @@ Contributors:
 #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
+ *    dest - pointer for new property list
- *    src : property list
+ *    src - property list
  *
  * Returns:
  *    MOSQ_ERR_SUCCESS - on successful copy

include/mosquitto_broker.h

@@ -16,6 +16,11 @@ Contributors:
    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_INFO
- *             MOSQ_LOG_NOTICE
+ *             * MOSQ_LOG_NOTICE
- *             MOSQ_LOG_WARNING
+ *             * MOSQ_LOG_WARNING
- *             MOSQ_LOG_ERR
+ *             * MOSQ_LOG_ERR
- *             MOSQ_LOG_DEBUG
+ *             * MOSQ_LOG_DEBUG
- *             MOSQ_LOG_SUBSCRIBE (not recommended for use by plugins)
+ *             * MOSQ_LOG_SUBSCRIBE (not recommended for use by plugins)
- *             MOSQ_LOG_UNSUBSCRIBE (not recommended for use by plugins)
+ *             * MOSQ_LOG_UNSUBSCRIBE (not recommended for use by plugins)
  *
  *             These values are defined in mosquitto.h.
  *
@@ -309,6 +383,7 @@ 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:
  *
+ * Returns:
  *   3 - for MQTT v3 / v3.1
  *   4 - for MQTT v3.1.1
  *   5 - for MQTT v5
@@ -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 @@ Contributors:
 #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>.
+ *	user_data -      The pointer provided in <mosquitto_plugin_init>.
- *	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
@@ -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>.
+ *	user_data -      The pointer provided in <mosquitto_auth_plugin_init>.
- *	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
@@ -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>.
+ *	user_data -      The pointer provided in <mosquitto_auth_plugin_init>.
- *	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.
- *	reload :         If set to false, this is the first time the function has
+ *	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>.
+ *	user_data -      The pointer provided in <mosquitto_auth_plugin_init>.
- *	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.
- *	reload :         If set to false, this is the first time the function has
+ *	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>.
+ *	user_data -   the pointer provided in <mosquitto_auth_plugin_init>.
- *	hint :        the psk_hint for the listener the client is connecting to.
+ *	hint -        the psk_hint for the listener the client is connecting to.
- *	identity :    the identity string provided by the client
+ *	identity -    the identity string provided by the client
- *	key :         a string where the hex PSK should be copied
+ *	key -         a string where the hex PSK should be copied
- *	max_key_len : the size of key
+ *	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>.
+ *	user_data -   the pointer provided in <mosquitto_auth_plugin_init>.
- *	method : the authentication method
+ *	method - the authentication method
- *	reauth : this is set to false if this is the first authentication attempt
+ *	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 - pointer to authentication data, or NULL
- *	data_in_len : length of data_in, in bytes
+ *	data_in_len - length of data_in, in bytes
- *	data_out : if your plugin wishes to send authentication data back to the
+ *	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.

include/mqtt_protocol.h

@@ -19,6 +19,11 @@ Contributors:
 #ifndef MQTT_PROTOCOL_H
 #define MQTT_PROTOCOL_H
 
+/*
+ * File: mqtt_protocol.h
+ *
+ * This header contains definitions of MQTT values as defined in the specifications.
+ */
 #define PROTOCOL_NAME_v31 "MQIsdp"
 #define PROTOCOL_VERSION_v31 3
 
@@ -48,6 +53,18 @@ Contributors:
 /* Mosquitto only: for distinguishing CONNECT and WILL properties */
 #define CMD_WILL 0x100
 
+/* Enum: mqtt311_connack_codes
+ *
+ * The CONNACK results for MQTT v3.1.1, and v3.1.
+ *
+ * Values:
+ *  CONNACK_ACCEPTED - 0
+ *  CONNACK_REFUSED_PROTOCOL_VERSION - 1
+ *  CONNACK_REFUSED_IDENTIFIER_REJECTED - 2
+ *  CONNACK_REFUSED_SERVER_UNAVAILABLE - 3
+ *  CONNACK_REFUSED_BAD_USERNAME_PASSWORD - 4
+ *  CONNACK_REFUSED_NOT_AUTHORIZED - 5
+ */
 enum mqtt311_connack_codes {
 	CONNACK_ACCEPTED = 0,
 	CONNACK_REFUSED_PROTOCOL_VERSION = 1,
@@ -57,7 +74,56 @@ enum mqtt311_connack_codes {
 	CONNACK_REFUSED_NOT_AUTHORIZED = 5,
 };
 
-
+/* Enum: mqtt5_return_codes
+ * The reason codes returned in various MQTT commands.
+ *
+ * Values:
+ *  MQTT_RC_SUCCESS - 0
+ *  MQTT_RC_NORMAL_DISCONNECTION - 0
+ *  MQTT_RC_GRANTED_QOS0 - 0
+ *  MQTT_RC_GRANTED_QOS1 - 1
+ *  MQTT_RC_GRANTED_QOS2 - 2
+ *  MQTT_RC_DISCONNECT_WITH_WILL_MSG - 4
+ *  MQTT_RC_NO_MATCHING_SUBSCRIBERS - 16
+ *  MQTT_RC_NO_SUBSCRIPTION_EXISTED - 17
+ *  MQTT_RC_CONTINUE_AUTHENTICATION - 24
+ *  MQTT_RC_REAUTHENTICATE - 25
+ *  MQTT_RC_UNSPECIFIED - 128
+ *  MQTT_RC_MALFORMED_PACKET - 129
+ *  MQTT_RC_PROTOCOL_ERROR - 130
+ *  MQTT_RC_IMPLEMENTATION_SPECIFIC - 131
+ *  MQTT_RC_UNSUPPORTED_PROTOCOL_VERSION - 132
+ *  MQTT_RC_CLIENTID_NOT_VALID - 133
+ *  MQTT_RC_BAD_USERNAME_OR_PASSWORD - 134
+ *  MQTT_RC_NOT_AUTHORIZED - 135
+ *  MQTT_RC_SERVER_UNAVAILABLE - 136
+ *  MQTT_RC_SERVER_BUSY - 137
+ *  MQTT_RC_BANNED - 138
+ *  MQTT_RC_SERVER_SHUTTING_DOWN - 139
+ *  MQTT_RC_BAD_AUTHENTICATION_METHOD - 140
+ *  MQTT_RC_KEEP_ALIVE_TIMEOUT - 141
+ *  MQTT_RC_SESSION_TAKEN_OVER - 142
+ *  MQTT_RC_TOPIC_FILTER_INVALID - 143
+ *  MQTT_RC_TOPIC_NAME_INVALID - 144
+ *  MQTT_RC_PACKET_ID_IN_USE - 145
+ *  MQTT_RC_PACKET_ID_NOT_FOUND - 146
+ *  MQTT_RC_RECEIVE_MAXIMUM_EXCEEDED - 147
+ *  MQTT_RC_TOPIC_ALIAS_INVALID - 148
+ *  MQTT_RC_PACKET_TOO_LARGE - 149
+ *  MQTT_RC_MESSAGE_RATE_TOO_HIGH - 150
+ *  MQTT_RC_QUOTA_EXCEEDED - 151
+ *  MQTT_RC_ADMINISTRATIVE_ACTION - 152
+ *  MQTT_RC_PAYLOAD_FORMAT_INVALID - 153
+ *  MQTT_RC_RETAIN_NOT_SUPPORTED - 154
+ *  MQTT_RC_QOS_NOT_SUPPORTED - 155
+ *  MQTT_RC_USE_ANOTHER_SERVER - 156
+ *  MQTT_RC_SERVER_MOVED - 157
+ *  MQTT_RC_SHARED_SUBS_NOT_SUPPORTED - 158
+ *  MQTT_RC_CONNECTION_RATE_EXCEEDED - 159
+ *  MQTT_RC_MAXIMUM_CONNECT_TIME - 160
+ *  MQTT_RC_SUBSCRIPTION_IDS_NOT_SUPPORTED - 161
+ *  MQTT_RC_WILDCARD_SUBS_NOT_SUPPORTED - 162
+ */
 enum mqtt5_return_codes {
 	MQTT_RC_SUCCESS = 0,						/* CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, UNSUBACK, AUTH */
 	MQTT_RC_NORMAL_DISCONNECTION = 0,			/* DISCONNECT */

src/plugin.c

@@ -313,7 +313,7 @@ int mosquitto_callback_unregister(
 			cb_base = &security_options->plugin_callbacks.disconnect;
 			break;
 		default:
-			return MOSQ_ERR_INVAL;
+			return MOSQ_ERR_NOT_SUPPORTED;
 			break;
 	}