From ce30f811bade4f0c1dee3dd7451f26c80f966a2b Mon Sep 17 00:00:00 2001 From: "Roger A. Light" Date: Tue, 22 Dec 2020 13:54:51 +0000 Subject: [PATCH] Improve API documentation. Fix return code on callback unregister. --- include/mosquitto.h | 11 +++- include/mosquitto_broker.h | 105 +++++++++++++++++++++++++++++++------ include/mosquitto_plugin.h | 76 ++++++++++++++------------- include/mqtt_protocol.h | 68 +++++++++++++++++++++++- src/plugin.c | 2 +- 5 files changed, 208 insertions(+), 54 deletions(-) diff --git a/include/mosquitto.h b/include/mosquitto.h index ef667693..5d12e075 100644 --- a/include/mosquitto.h +++ b/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 - * src : property list + * dest - pointer for new property list + * src - property list * * Returns: * MOSQ_ERR_SUCCESS - on successful copy diff --git a/include/mosquitto_broker.h b/include/mosquitto_broker.h index 6f23a71c..d1a26319 100644 --- a/include/mosquitto_broker.h +++ b/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 . + * 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 . + * 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 * * ========================================================================= */ diff --git a/include/mosquitto_plugin.h b/include/mosquitto_plugin.h index 0e4207a9..4199c7b3 100644 --- a/include/mosquitto_plugin.h +++ b/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 . - * opts : Pointer to an array of struct mosquitto_opt, which + * user_data - The pointer provided in . + * 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 . - * opts : Pointer to an array of struct mosquitto_opt, which + * user_data - The pointer provided in . + * 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 . - * opts : Pointer to an array of struct mosquitto_opt, which + * user_data - The pointer provided in . + * 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 . - * opts : Pointer to an array of struct mosquitto_opt, which + * user_data - The pointer provided in . + * 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 . - * 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 . + * 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 . - * method : the authentication method - * reauth : this is set to false if this is the first authentication attempt + * user_data - the pointer provided in . + * 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. diff --git a/include/mqtt_protocol.h b/include/mqtt_protocol.h index a2a55e89..86d7dc99 100644 --- a/include/mqtt_protocol.h +++ b/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 */ diff --git a/src/plugin.c b/src/plugin.c index 899cf5db..34fddf26 100644 --- a/src/plugin.c +++ b/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; }