This header contains functions for use by plugins.
| mosquitto_broker.h | This header contains functions for use by plugins. |
| Register callbacks. | |
| Functions | |
| mosquitto_callback_register | Register a callback for an event. |
| mosquitto_callback_unregister | Unregister a previously registered callback function. |
| Memory allocation. | Use these functions when allocating or freeing memory to have your memory included in the memory tracking on the broker. |
| Functions | |
| mosquitto_calloc | |
| mosquitto_free | |
| mosquitto_malloc | |
| mosquitto_realloc | |
| mosquitto_strdup | |
| Utility Functions | Use these functions from within your plugin. |
| Functions | |
| mosquitto_log_printf | Write a log message using the broker configured logging. |
| mosquitto_client_address | Retrieve the IP address of the client as a string. |
| mosquitto_client_clean_session | Retrieve the clean session flag value for a client. |
| mosquitto_client_id | Retrieve the client id associated with a client. |
| mosquitto_client_keepalive | Retrieve the keepalive value for a client. |
| mosquitto_client_certificate | If TLS support is enabled, return the certificate provided by a client as an X509 pointer from openssl. |
| mosquitto_client_protocol | mp_mqtt (MQTT over TCP) mp_mqttsn (MQTT-SN) mp_websockets (MQTT over Websockets) |
| mosquitto_client_protocol_version | |
| mosquitto_client_sub_count | Retrieve the number of subscriptions that have been made by a client. |
| mosquitto_client_username | Retrieve the username associated with a client. |
| mosquitto_set_username | Set the username for a client. |
| Client control | |
| Functions | |
| mosquitto_kick_client_by_clientid | Forcefully disconnect a client from the broker. |
| mosquitto_kick_client_by_username | Forcefully disconnect a client from the broker. |
| Publishing functions | |
| Functions | |
| mosquitto_broker_publish | Publish a message from within a plugin. |
| mosquitto_broker_publish_copy | Publish a message from within a plugin. |
| Functions | |
| mosquitto_callback_register | Register a callback for an event. |
| mosquitto_callback_unregister | Unregister a previously registered callback function. |
mosq_EXPORT int mosquitto_callback_register( mosquitto_plugin_id_t * identifier, int event, MOSQ_FUNC_generic_callback cb_func, const void * event_data, void * userdata )
Register a callback for an event.
| identifier | the plugin identifier, as provided by mosquitto_plugin_init. |
| event | the event to register a callback for. Can be one of: |
| cb_func | the callback function |
| event_data | event specific data |
| 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_unregister( mosquitto_plugin_id_t * identifier, int event, MOSQ_FUNC_generic_callback cb_func, const void * event_data )
Unregister a previously registered callback function.
| identifier | the plugin identifier, as provided by mosquitto_plugin_init. |
| event | the event to register a callback for. Can be one of: |
| cb_func | the callback function |
| event_data | event specific data |
| 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 |
Use these functions from within your plugin.
| Functions | |
| mosquitto_log_printf | Write a log message using the broker configured logging. |
| mosquitto_client_address | Retrieve the IP address of the client as a string. |
| mosquitto_client_clean_session | Retrieve the clean session flag value for a client. |
| mosquitto_client_id | Retrieve the client id associated with a client. |
| mosquitto_client_keepalive | Retrieve the keepalive value for a client. |
| mosquitto_client_certificate | If TLS support is enabled, return the certificate provided by a client as an X509 pointer from openssl. |
| mosquitto_client_protocol | mp_mqtt (MQTT over TCP) mp_mqttsn (MQTT-SN) mp_websockets (MQTT over Websockets) |
| mosquitto_client_protocol_version | |
| mosquitto_client_sub_count | Retrieve the number of subscriptions that have been made by a client. |
| mosquitto_client_username | Retrieve the username associated with a client. |
| mosquitto_set_username | Set the username for a client. |
mosq_EXPORT void mosquitto_log_printf( int level, const char * fmt, ... )
Write a log message using the broker configured logging.
| level | Log message priority. Can currently be one of: |
These values are defined in mosquitto.h.
| fmt, ... | printf style format and arguments. |
mosq_EXPORT void *mosquitto_client_certificate( const struct mosquitto * client )
If TLS support is enabled, return the certificate provided by a client as an X509 pointer from openssl. If the client did not provide a certificate, then NULL will be returned. This function will only ever return a non-NULL value if the `require_certificate` option is set to true.
When you have finished with the x509 pointer, it must be freed using X509_free().
If TLS is not supported, this function will always return NULL.
mosq_EXPORT int mosquitto_set_username( struct mosquitto * client, const char * username )
Set the username for a client.
This removes and replaces the current username for a client and hence updates its access.
username can be NULL, in which case the client will become anonymous, but must not be zero length.
In the case of error, the client will be left with its original username.
| MOSQ_ERR_SUCCESS | on success |
| MOSQ_ERR_INVAL | if client is NULL, or if username is zero length |
| MOSQ_ERR_NOMEM | on out of memory |
| Functions | |
| mosquitto_kick_client_by_clientid | Forcefully disconnect a client from the broker. |
| mosquitto_kick_client_by_username | Forcefully disconnect a client from the broker. |
mosq_EXPORT int mosquitto_kick_client_by_clientid( const char * clientid, bool with_will )
Forcefully disconnect a client from the broker.
If clientid != NULL, then the client with the matching client id is disconnected from the broker. If clientid == NULL, then all clients are disconnected from the broker.
If with_will == true, then if the client has a Last Will and Testament defined then this will be sent. If false, the LWT will not be sent.
mosq_EXPORT int mosquitto_kick_client_by_username( const char * username, bool with_will )
Forcefully disconnect a client from the broker.
If username != NULL, then all clients with a matching username are kicked from the broker. If username == NULL, then all clients that do not have a username are kicked.
If with_will == true, then if the client has a Last Will and Testament defined then this will be sent. If false, the LWT will not be sent.
| Functions | |
| mosquitto_broker_publish | Publish a message from within a plugin. |
| mosquitto_broker_publish_copy | Publish a message from within a plugin. |
mosq_EXPORT int mosquitto_broker_publish( const char * clientid, const char * topic, int payloadlen, void * payload, int qos, bool retain, mosquitto_property * properties )
Publish a message from within a plugin.
This function allows a plugin to publish a message. Messages published in this way are treated as coming from the broker and so will not be passed to `mosquitto_auth_acl_check(, MOSQ_ACL_WRITE, , )` for checking. Read access will be enforced as normal for individual clients when they are due to receive the message.
It can be used to send messages to all clients that have a matching subscription, or to a single client whether or not it has a matching subscription.
| clientid | optional string. If set to NULL, the message is delivered to all clients. If non-NULL, the message is delivered only to the client with the corresponding client id. If the client id specified is not connected, the message will be dropped. |
| topic | message topic |
| payloadlen | payload length in bytes. Can be 0 for an empty payload. |
| payload | payload bytes. If payloadlen > 0 this must not be NULL. Must be allocated on the heap. Will be freed by mosquitto after use if the function returns success. |
| qos | message QoS to use. |
| retain | should retain be set on the message. This does not apply if clientid is non-NULL. |
| properties | MQTT v5 properties to attach to the message. If the function returns success, then properties is owned by the broker and will be freed at a later point. |
| MOSQ_ERR_SUCCESS | on success |
| MOSQ_ERR_INVAL | if topic is NULL, if payloadlen < 0, if payloadlen > 0 and payload is NULL, if qos is not 0, 1, or 2. |
| MOSQ_ERR_NOMEM | on out of memory |
mosq_EXPORT int mosquitto_broker_publish_copy( const char * clientid, const char * topic, int payloadlen, const void * payload, int qos, bool retain, mosquitto_property * properties )
Publish a message from within a plugin.
This function is identical to mosquitto_broker_publish, except that a copy of `payload` is taken.
| clientid | optional string. If set to NULL, the message is delivered to all clients. If non-NULL, the message is delivered only to the client with the corresponding client id. If the client id specified is not connected, the message will be dropped. |
| topic | message topic |
| payloadlen | payload length in bytes. Can be 0 for an empty payload. |
| payload | payload bytes. If payloadlen > 0 this must not be NULL. Memory remains the property of the calling function. |
| qos | message QoS to use. |
| retain | should retain be set on the message. This does not apply if clientid is non-NULL. |
| properties | MQTT v5 properties to attach to the message. If the function returns success, then properties is owned by the broker and will be freed at a later point. |
| MOSQ_ERR_SUCCESS | on success |
| MOSQ_ERR_INVAL | if topic is NULL, if payloadlen < 0, if payloadlen > 0 and payload is NULL, if qos is not 0, 1, or 2. |
| MOSQ_ERR_NOMEM | on out of memory |
Register a callback for an event.
mosq_EXPORT int mosquitto_callback_register( mosquitto_plugin_id_t * identifier, int event, MOSQ_FUNC_generic_callback cb_func, const void * event_data, void * userdata )
Unregister a previously registered callback function.
mosq_EXPORT int mosquitto_callback_unregister( mosquitto_plugin_id_t * identifier, int event, MOSQ_FUNC_generic_callback cb_func, const void * event_data )
mosq_EXPORT void *mosquitto_calloc( size_t nmemb, size_t size )
mosq_EXPORT void mosquitto_free( void * mem )
mosq_EXPORT void *mosquitto_malloc( size_t size )
mosq_EXPORT void *mosquitto_realloc( void * ptr, size_t size )
mosq_EXPORT char *mosquitto_strdup( const char * s )
Write a log message using the broker configured logging.
mosq_EXPORT void mosquitto_log_printf( int level, const char * fmt, ... )
Retrieve the IP address of the client as a string.
mosq_EXPORT const char *mosquitto_client_address( const struct mosquitto * client )
Retrieve the clean session flag value for a client.
mosq_EXPORT bool mosquitto_client_clean_session( const struct mosquitto * client )
Retrieve the client id associated with a client.
mosq_EXPORT const char *mosquitto_client_id( const struct mosquitto * client )
Retrieve the keepalive value for a client.
mosq_EXPORT int mosquitto_client_keepalive( const struct mosquitto * client )
If TLS support is enabled, return the certificate provided by a client as an X509 pointer from openssl.
mosq_EXPORT void *mosquitto_client_certificate( const struct mosquitto * client )
mp_mqtt (MQTT over TCP) mp_mqttsn (MQTT-SN) mp_websockets (MQTT over Websockets)
mosq_EXPORT int mosquitto_client_protocol( const struct mosquitto * client )
mosq_EXPORT int mosquitto_client_protocol_version( const struct mosquitto * client )
Retrieve the number of subscriptions that have been made by a client.
mosq_EXPORT int mosquitto_client_sub_count( const struct mosquitto * client )
Retrieve the username associated with a client.
mosq_EXPORT const char *mosquitto_client_username( const struct mosquitto * client )
Set the username for a client.
mosq_EXPORT int mosquitto_set_username( struct mosquitto * client, const char * username )
Forcefully disconnect a client from the broker.
mosq_EXPORT int mosquitto_kick_client_by_clientid( const char * clientid, bool with_will )
Forcefully disconnect a client from the broker.
mosq_EXPORT int mosquitto_kick_client_by_username( const char * username, bool with_will )
Publish a message from within a plugin.
mosq_EXPORT int mosquitto_broker_publish( const char * clientid, const char * topic, int payloadlen, void * payload, int qos, bool retain, mosquitto_property * properties )
Publish a message from within a plugin.
mosq_EXPORT int mosquitto_broker_publish_copy( const char * clientid, const char * topic, int payloadlen, const void * payload, int qos, bool retain, mosquitto_property * properties )
Called after the plugin has been loaded and mosquitto_plugin_version has been called.
mosq_plugin_EXPORT int mosquitto_plugin_init( mosquitto_plugin_id_t * identifier, void ** userdata, struct mosquitto_opt * options, int option_count )