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

Improve API documentation.

Browse Source 
Fix return code on callback unregister.
pull/1976/head
Roger A. Light 5 years ago
parent 31ac9c77cb
commit ce30f811ba
5 changed files with 208 additions and 54 deletions
Show Stats Download Patch File Download Diff File

11
include/mosquitto.h
Unescape Escape View File

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

99
include/mosquitto_broker.h
Unescape Escape View File

@ -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_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,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
*
* ========================================================================= */

76
include/mosquitto_plugin.h
Unescape Escape View File

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

68
include/mqtt_protocol.h
Unescape Escape View File

@ -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 */

2
src/plugin.c
Unescape Escape View File

@ -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;
}

Write Preview
Loading…
Cancel
Save