mosquitto.h

libmosq_EXPORT int mosquitto_lib_version( int  * major, int  * minor, int  * revision )

Can be used to obtain version information for the mosquitto library.  This allows the application to compare the library version against the version it was compiled against by using the LIBMOSQUITTO_MAJOR, LIBMOSQUITTO_MINOR and LIBMOSQUITTO_REVISION defines.

Parameters

Returns

libmosq_EXPORT int mosquitto_lib_init( void )

Must be called before any other mosquitto functions.

This function is not thread safe.

Returns

See Also

mosquitto_lib_cleanup, mosquitto_lib_version

libmosq_EXPORT int mosquitto_lib_cleanup( void )

Call to free resources associated with the library.

Returns

See Also

mosquitto_lib_init, mosquitto_lib_version

libmosq_EXPORT struct mosquitto *mosquitto_new( const  char  * id, bool  clean_session, void  * obj )

Create a new mosquitto client instance.

Parameters

Returns

Pointer to a struct mosquitto on success.  NULL on failure.  Interrogate errno to determine the cause for the failure:

• ENOMEM on out of memory.
• EINVAL on invalid input parameters.

See Also

mosquitto_reinitialise, mosquitto_destroy, mosquitto_user_data_set

libmosq_EXPORT void mosquitto_destroy( struct  mosquitto  * mosq )

Use to free memory associated with a mosquitto client instance.

Parameters

See Also

mosquitto_new, mosquitto_reinitialise

libmosq_EXPORT int mosquitto_reinitialise( struct  mosquitto  * mosq, const  char  * id, bool  clean_session, void  * obj )

This function allows an existing mosquitto client to be reused.  Call on a mosquitto instance to close any open network connections, free memory and reinitialise the client with the new parameters.  The end result is the same as the output of mosquitto_new.

Parameters

Returns

See Also

mosquitto_new, mosquitto_destroy

libmosq_EXPORT int mosquitto_will_set( struct  mosquitto  * mosq, const  char  * topic, int  payloadlen, const  void  * payload, int  qos, bool  retain )

Configure will information for a mosquitto instance.  By default, clients do not have a will.  This must be called before calling mosquitto_connect.

It is valid to use this function for clients using all MQTT protocol versions.  If you need to set MQTT v5 Will properties, use mosquitto_will_set_v5 instead.

Parameters

Returns

libmosq_EXPORT int mosquitto_will_set_v5( struct  mosquitto  * mosq, const  char  * topic, int  payloadlen, const  void  * payload, int  qos, bool  retain, mosquitto_property  * properties )

Configure will information for a mosquitto instance, with attached properties.  By default, clients do not have a will.  This must be called before calling mosquitto_connect.

If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument will be applied to the Will.  For MQTT v3.1.1 and below, the `properties` argument will be ignored.

Set your client to use MQTT v5 immediately after it is created

mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5);

Parameters

Returns

libmosq_EXPORT int mosquitto_will_clear( struct  mosquitto  * mosq )

Remove a previously configured will.  This must be called before calling mosquitto_connect.

Parameters

Returns

libmosq_EXPORT int mosquitto_username_pw_set( struct  mosquitto  * mosq, const  char  * username, const  char  * password )

Configure username and password for a mosquitto instance.  By default, no username or password will be sent.  For v3.1 and v3.1.1 clients, if username is NULL, the password argument is ignored.

This is must be called before calling mosquitto_connect.

Parameters

Returns

libmosq_EXPORT int mosquitto_connect( struct  mosquitto  * mosq, const  char  * host, int  port, int  keepalive )

Connect to an MQTT broker.

It is valid to use this function for clients using all MQTT protocol versions.  If you need to set MQTT v5 CONNECT properties, use mosquitto_connect_bind_v5 instead.

Parameters

Returns

• mosq == NULL
• host == NULL
• port < 0
• keepalive < 5

See Also

mosquitto_connect_bind, mosquitto_connect_async, mosquitto_reconnect, mosquitto_disconnect, mosquitto_tls_set

libmosq_EXPORT int mosquitto_connect_bind( struct  mosquitto  * mosq, const  char  * host, int  port, int  keepalive, const  char  * bind_address )

Connect to an MQTT broker.  This extends the functionality of mosquitto_connect by adding the bind_address parameter.  Use this function if you need to restrict network communication over a particular interface.

Parameters

Returns

See Also

mosquitto_connect, mosquitto_connect_async, mosquitto_connect_bind_async

libmosq_EXPORT int mosquitto_connect_bind_v5(     struct  mosquitto  * mosq,     const  char  * host,     int  port,     int  keepalive,     const  char  * bind_address,     const  mosquitto_property  * properties )

Connect to an MQTT broker.  This extends the functionality of mosquitto_connect by adding the bind_address parameter and MQTT v5 properties.  Use this function if you need to restrict network communication over a particular interface.

Use e.g.  mosquitto_property_add_string and similar to create a list of properties, then attach them to this publish.  Properties need freeing with mosquitto_property_free_all.

If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument will be applied to the CONNECT message.  For MQTT v3.1.1 and below, the `properties` argument will be ignored.

Set your client to use MQTT v5 immediately after it is created

mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5);

Parameters

Returns

• mosq == NULL
• host == NULL
• port < 0
• keepalive < 5

See Also

mosquitto_connect, mosquitto_connect_async, mosquitto_connect_bind_async

libmosq_EXPORT int mosquitto_connect_async( struct  mosquitto  * mosq, const  char  * host, int  port, int  keepalive )

Connect to an MQTT broker.  This is a non-blocking call.  If you use mosquitto_connect_async your client must use the threaded interface mosquitto_loop_start.  If you need to use mosquitto_loop, you must use mosquitto_connect to connect the client.

May be called before or after mosquitto_loop_start.

Parameters

Returns

See Also

mosquitto_connect_bind_async, mosquitto_connect, mosquitto_reconnect, mosquitto_disconnect, mosquitto_tls_set

libmosq_EXPORT int mosquitto_connect_bind_async( struct  mosquitto  * mosq, const  char  * host, int  port, int  keepalive, const  char  * bind_address )

Connect to an MQTT broker.  This is a non-blocking call.  If you use mosquitto_connect_bind_async your client must use the threaded interface mosquitto_loop_start.  If you need to use mosquitto_loop, you must use mosquitto_connect to connect the client.

This extends the functionality of mosquitto_connect_async by adding the bind_address parameter.  Use this function if you need to restrict network communication over a particular interface.

May be called before or after mosquitto_loop_start.

Parameters

Returns

• mosq == NULL
• host == NULL
• port < 0
• keepalive < 5

See Also

mosquitto_connect_async, mosquitto_connect, mosquitto_connect_bind

libmosq_EXPORT int mosquitto_connect_srv( struct  mosquitto  * mosq, const  char  * host, int  keepalive, const  char  * bind_address )

Connect to an MQTT broker.

If you set `host` to `example.com`, then this call will attempt to retrieve the DNS SRV record for `_secure-mqtt._tcp.example.com` or `_mqtt._tcp.example.com` to discover which actual host to connect to.

DNS SRV support is not usually compiled in to libmosquitto, use of this call is not recommended.

Parameters

Returns

• mosq == NULL
• host == NULL
• port < 0
• keepalive < 5

See Also

mosquitto_connect_async, mosquitto_connect, mosquitto_connect_bind

libmosq_EXPORT int mosquitto_reconnect( struct  mosquitto  * mosq )

Reconnect to a broker.

This function provides an easy way of reconnecting to a broker after a connection has been lost.  It uses the values that were provided in the mosquitto_connect call.  It must not be called before mosquitto_connect.

Parameters

Returns

See Also

mosquitto_connect, mosquitto_disconnect, mosquitto_reconnect_async

libmosq_EXPORT int mosquitto_reconnect_async( struct  mosquitto  * mosq )

Reconnect to a broker.  Non blocking version of mosquitto_reconnect.

This function provides an easy way of reconnecting to a broker after a connection has been lost.  It uses the values that were provided in the mosquitto_connect or mosquitto_connect_async calls.  It must not be called before mosquitto_connect.

Parameters

Returns

See Also

mosquitto_connect, mosquitto_disconnect

libmosq_EXPORT int mosquitto_disconnect( struct  mosquitto  * mosq )

Disconnect from the broker.

It is valid to use this function for clients using all MQTT protocol versions.  If you need to set MQTT v5 DISCONNECT properties, use mosquitto_disconnect_v5 instead.

Parameters

Returns

libmosq_EXPORT int mosquitto_disconnect_v5(     struct  mosquitto  * mosq,     int  reason_code,     const  mosquitto_property  * properties )

Disconnect from the broker, with attached MQTT properties.

Use e.g.  mosquitto_property_add_string and similar to create a list of properties, then attach them to this publish.  Properties need freeing with mosquitto_property_free_all.

If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument will be applied to the DISCONNECT message.  For MQTT v3.1.1 and below, the `properties` argument will be ignored.

Set your client to use MQTT v5 immediately after it is created

mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5);

Parameters

Returns

libmosq_EXPORT int mosquitto_publish( struct  mosquitto  * mosq, int  * mid, const  char  * topic, int  payloadlen, const  void  * payload, int  qos, bool  retain )

Publish a message on a given topic.

It is valid to use this function for clients using all MQTT protocol versions.  If you need to set MQTT v5 PUBLISH properties, use mosquitto_publish_v5 instead.

Parameters

Returns

See Also

mosquitto_max_inflight_messages_set

libmosq_EXPORT int mosquitto_publish_v5( struct  mosquitto  * mosq, int  * mid, const  char  * topic, int  payloadlen, const  void  * payload, int  qos, bool  retain, const  mosquitto_property  * properties )

Publish a message on a given topic, with attached MQTT properties.

Use e.g.  mosquitto_property_add_string and similar to create a list of properties, then attach them to this publish.  Properties need freeing with mosquitto_property_free_all.

If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument will be applied to the PUBLISH message.  For MQTT v3.1.1 and below, the `properties` argument will be ignored.

Set your client to use MQTT v5 immediately after it is created

mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5);

Parameters

Returns

libmosq_EXPORT int mosquitto_subscribe( struct  mosquitto  * mosq, int  * mid, const  char  * sub, int  qos )

Subscribe to a topic.

It is valid to use this function for clients using all MQTT protocol versions.  If you need to set MQTT v5 SUBSCRIBE properties, use mosquitto_subscribe_v5 instead.

Parameters

Returns

libmosq_EXPORT int mosquitto_subscribe_v5( struct  mosquitto  * mosq, int  * mid, const  char  * sub, int  qos, int  options, const  mosquitto_property  * properties )

Subscribe to a topic, with attached MQTT properties.

Use e.g.  mosquitto_property_add_string and similar to create a list of properties, then attach them to this publish.  Properties need freeing with mosquitto_property_free_all.

If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument will be applied to the PUBLISH message.  For MQTT v3.1.1 and below, the `properties` argument will be ignored.

Set your client to use MQTT v5 immediately after it is created

mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5);

Parameters

Returns

libmosq_EXPORT int mosquitto_subscribe_multiple(     struct  mosquitto  * mosq,     int  * mid,     int  sub_count,     char *const  *const  sub,     int  qos,     int  options,     const  mosquitto_property  * properties )

Subscribe to multiple topics.

Parameters

Returns

libmosq_EXPORT int mosquitto_unsubscribe( struct  mosquitto  * mosq, int  * mid, const  char  * sub )

Unsubscribe from a topic.

Parameters

Returns

libmosq_EXPORT int mosquitto_unsubscribe_v5(     struct  mosquitto  * mosq,     int  * mid,     const  char  * sub,     const  mosquitto_property  * properties )

Unsubscribe from a topic, with attached MQTT properties.

It is valid to use this function for clients using all MQTT protocol versions.  If you need to set MQTT v5 UNSUBSCRIBE properties, use mosquitto_unsubscribe_v5 instead.

Use e.g.  mosquitto_property_add_string and similar to create a list of properties, then attach them to this publish.  Properties need freeing with mosquitto_property_free_all.

If the mosquitto instance `mosq` is using MQTT v5, the `properties` argument will be applied to the PUBLISH message.  For MQTT v3.1.1 and below, the `properties` argument will be ignored.

Set your client to use MQTT v5 immediately after it is created

mosquitto_int_option(mosq, MOSQ_OPT_PROTOCOL_VERSION, MQTT_PROTOCOL_V5);

Parameters

Returns

libmosq_EXPORT int mosquitto_unsubscribe_multiple(     struct  mosquitto  * mosq,     int  * mid,     int  sub_count,     char *const  *const  sub,     const  mosquitto_property  * properties )

Unsubscribe from multiple topics.

Parameters

Returns

libmosq_EXPORT int mosquitto_message_copy( struct  mosquitto_message  * dst, const struct  mosquitto_message  * src )

Copy the contents of a mosquitto message to another message.  Useful for preserving a message received in the on_message() callback.

Parameters

Returns

See Also

mosquitto_message_free

libmosq_EXPORT void mosquitto_message_free( struct  mosquitto_message  ** message )

Completely free a mosquitto_message struct.

Parameters

See Also

mosquitto_message_copy, mosquitto_message_free_contents

libmosq_EXPORT void mosquitto_message_free_contents(     struct  mosquitto_message  * message )

Free a mosquitto_message struct contents, leaving the struct unaffected.

Parameters

See Also

mosquitto_message_copy, mosquitto_message_free

libmosq_EXPORT int mosquitto_loop_forever( struct  mosquitto  * mosq, int  timeout, int  max_packets )

This function call loop() for you in an infinite blocking loop.  It is useful for the case where you only want to run the MQTT client loop in your program.

It handles reconnecting in case server connection is lost.  If you call mosquitto_disconnect() in a callback it will return.

Parameters

Returns

See Also

mosquitto_loop, mosquitto_loop_start

libmosq_EXPORT int mosquitto_loop_start( struct  mosquitto  * mosq )

This is part of the threaded client interface.  Call this once to start a new thread to process network traffic.  This provides an alternative to repeatedly calling mosquitto_loop yourself.

Parameters

Returns

See Also

mosquitto_connect_async, mosquitto_loop, mosquitto_loop_forever, mosquitto_loop_stop

libmosq_EXPORT int mosquitto_loop_stop( struct  mosquitto  * mosq, bool  force )

This is part of the threaded client interface.  Call this once to stop the network thread previously created with mosquitto_loop_start.  This call will block until the network thread finishes.  For the network thread to end, you must have previously called mosquitto_disconnect or have set the force parameter to true.

Parameters

Returns

See Also

mosquitto_loop, mosquitto_loop_start

libmosq_EXPORT int mosquitto_loop( struct  mosquitto  * mosq, int  timeout, int  max_packets )

The main network loop for the client.  This must be called frequently to keep communications between the client and broker working.  This is carried out by mosquitto_loop_forever and mosquitto_loop_start, which are the recommended ways of handling the network loop.  You may also use this function if you wish.  It must not be called inside a callback.

If incoming data is present it will then be processed.  Outgoing commands, from e.g.  mosquitto_publish, are normally sent immediately that their function is called, but this is not always possible.  mosquitto_loop will also attempt to send any remaining outgoing messages, which also includes commands that are part of the flow for messages with QoS>0.

This calls select() to monitor the client network socket.  If you want to integrate mosquitto client operation with your own select() call, use mosquitto_socket, mosquitto_loop_read, mosquitto_loop_write and mosquitto_loop_misc.

Threads

Parameters

Returns

libmosq_EXPORT int mosquitto_loop_read( struct  mosquitto  * mosq, int  max_packets )

Carry out network read operations.  This should only be used if you are not using mosquitto_loop() and are monitoring the client network socket for activity yourself.

Parameters

Returns

See Also

mosquitto_socket, mosquitto_loop_write, mosquitto_loop_misc

libmosq_EXPORT int mosquitto_loop_write( struct  mosquitto  * mosq, int  max_packets )

Carry out network write operations.  This should only be used if you are not using mosquitto_loop() and are monitoring the client network socket for activity yourself.

Parameters

Returns

See Also

mosquitto_socket, mosquitto_loop_read, mosquitto_loop_misc, mosquitto_want_write

libmosq_EXPORT int mosquitto_loop_misc( struct  mosquitto  * mosq )

Carry out miscellaneous operations required as part of the network loop.  This should only be used if you are not using mosquitto_loop() and are monitoring the client network socket for activity yourself.

This function deals with handling PINGs and checking whether messages need to be retried, so should be called fairly frequently, around once per second is sufficient.

Parameters

Returns

See Also

mosquitto_socket, mosquitto_loop_read, mosquitto_loop_write

libmosq_EXPORT int mosquitto_socket( struct  mosquitto  * mosq )

Return the socket handle for a mosquitto instance.  Useful if you want to include a mosquitto client in your own select() calls.

Parameters

Returns

The socket for the mosquitto client or -1 on failure.

libmosq_EXPORT bool mosquitto_want_write( struct  mosquitto  * mosq )

Returns true if there is data ready to be written on the socket.

Parameters

See Also

mosquitto_socket, mosquitto_loop_read, mosquitto_loop_write

libmosq_EXPORT int mosquitto_threaded_set( struct  mosquitto  * mosq, bool  threaded )

Used to tell the library that your application is using threads, but not using mosquitto_loop_start.  The library operates slightly differently when not in threaded mode in order to simplify its operation.  If you are managing your own threads and do not use this function you will experience crashes due to race conditions.

When using mosquitto_loop_start, this is set automatically.

Parameters

libmosq_EXPORT int mosquitto_opts_set( struct  mosquitto  * mosq, enum  mosq_opt_t  option, void  * value )

Used to set options for the client.

This function is deprecated, the replacement mosquitto_int_option, mosquitto_string_option and mosquitto_void_option functions should be used instead.

Parameters

Options

libmosq_EXPORT int mosquitto_int_option( struct  mosquitto  * mosq, enum  mosq_opt_t  option, int  value )

Used to set integer options for the client.

Parameters

Options

libmosq_EXPORT int mosquitto_string_option( struct  mosquitto  * mosq, enum  mosq_opt_t  option, const  char  * value )

Used to set const char* options for the client.

Parameters

Options

libmosq_EXPORT int mosquitto_void_option( struct  mosquitto  * mosq, enum  mosq_opt_t  option, void  * value )

Used to set void* options for the client.

Parameters

Options

libmosq_EXPORT int mosquitto_reconnect_delay_set(     struct  mosquitto  * mosq,     unsigned  int  reconnect_delay,     unsigned  int  reconnect_delay_max,     bool  reconnect_exponential_backoff )

Control the behaviour of the client when it has unexpectedly disconnected in mosquitto_loop_forever or after mosquitto_loop_start.  The default behaviour if this function is not used is to repeatedly attempt to reconnect with a delay of 1 second until the connection succeeds.

Use reconnect_delay parameter to change the delay between successive reconnection attempts.  You may also enable exponential backoff of the time between reconnections by setting reconnect_exponential_backoff to true and set an upper bound on the delay with reconnect_delay_max.

Example 1

delay=2, delay_max=10, exponential_backoff=False Delays would be: 2, 4, 6, 8, 10, 10, ...

Example 2

delay=3, delay_max=30, exponential_backoff=True Delays would be: 3, 6, 12, 24, 30, 30, ...

Parameters

Returns

libmosq_EXPORT int mosquitto_max_inflight_messages_set(     struct  mosquitto  * mosq,     unsigned  int  max_inflight_messages )

This function is deprected.  Use the mosquitto_int_option function with the MOSQ_OPT_SEND_MAXIMUM option instead.

Set the number of QoS 1 and 2 messages that can be “in flight” at one time.  An in flight message is part way through its delivery flow.  Attempts to send further messages with mosquitto_publish will result in the messages being queued until the number of in flight messages reduces.

A higher number here results in greater message throughput, but if set higher than the maximum in flight messages on the broker may lead to delays in the messages being acknowledged.

Set to 0 for no maximum.

Parameters

Returns

libmosq_EXPORT void mosquitto_message_retry_set( struct  mosquitto  * mosq, unsigned  int  message_retry )

This function now has no effect.

libmosq_EXPORT void mosquitto_user_data_set( struct  mosquitto  * mosq, void  * obj )

When mosquitto_new is called, the pointer given as the “obj” parameter will be passed to the callbacks as user data.  The mosquitto_user_data_set function allows this obj parameter to be updated at any time.  This function will not modify the memory pointed to by the current user data pointer.  If it is dynamically allocated memory you must free it yourself.

Parameters

libmosq_EXPORT void *mosquitto_userdata( struct  mosquitto  * mosq )

Retrieve the “userdata” variable for a mosquitto client.

Parameters

Returns

A pointer to the userdata member variable.

libmosq_EXPORT int mosquitto_tls_set(     struct  mosquitto  * mosq,     const  char  * cafile,     const  char  * capath,     const  char  * certfile,     const  char  * keyfile,     int  (*pw_callback)(char *buf, int size, int rwflag, void *userdata) )

Configure the client for certificate based SSL/TLS support.  Must be called before mosquitto_connect.

Cannot be used in conjunction with mosquitto_tls_psk_set.

Define the Certificate Authority certificates to be trusted (ie. the server certificate must be signed with one of these certificates) using cafile.

If the server you are connecting to requires clients to provide a certificate, define certfile and keyfile with your client certificate and private key.  If your private key is encrypted, provide a password callback function or you will have to enter the password at the command line.

Parameters

Returns

See Also

mosquitto_tls_opts_set, mosquitto_tls_psk_set, mosquitto_tls_insecure_set, mosquitto_userdata

libmosq_EXPORT int mosquitto_tls_insecure_set( struct  mosquitto  * mosq, bool  value )

Configure verification of the server hostname in the server certificate.  If value is set to true, it is impossible to guarantee that the host you are connecting to is not impersonating your server.  This can be useful in initial server testing, but makes it possible for a malicious third party to impersonate your server through DNS spoofing, for example.  Do not use this function in a real system.  Setting value to true makes the connection encryption pointless.  Must be called before mosquitto_connect.

Parameters

Returns

See Also

mosquitto_tls_set

libmosq_EXPORT int mosquitto_tls_opts_set( struct  mosquitto  * mosq, int  cert_reqs, const  char  * tls_version, const  char  * ciphers )

Set advanced SSL/TLS options.  Must be called before mosquitto_connect.

Parameters

• SSL_VERIFY_NONE (0): the server will not be verified in any way.
• SSL_VERIFY_PEER (1): the server certificate will be verified and the connection aborted if the verification fails.  The default and recommended value is SSL_VERIFY_PEER.  Using SSL_VERIFY_NONE provides no security.

Returns

See Also

mosquitto_tls_set

libmosq_EXPORT int mosquitto_tls_psk_set( struct  mosquitto  * mosq, const  char  * psk, const  char  * identity, const  char  * ciphers )

Configure the client for pre-shared-key based TLS support.  Must be called before mosquitto_connect.

Cannot be used in conjunction with mosquitto_tls_set.

Parameters

Returns

See Also

mosquitto_tls_set

libmosq_EXPORT void *mosquitto_ssl_get( struct  mosquitto  * mosq )

Retrieve a pointer to the SSL structure used for TLS connections in this client.  This can be used in e.g. the connect callback to carry out additional verification steps.

Parameters

Returns

libmosq_EXPORT void mosquitto_connect_callback_set(     struct  mosquitto  * mosq,     void  (*on_connect)(struct mosquitto *, void *, int) )

Set the connect callback.  This is called when the broker sends a CONNACK message in response to a connection.

Parameters

Callback Parameters

libmosq_EXPORT void mosquitto_connect_with_flags_callback_set(     struct  mosquitto  * mosq,     void  (*on_connect)(struct mosquitto *, void *, int, int) )

Set the connect callback.  This is called when the broker sends a CONNACK message in response to a connection.

Parameters

Callback Parameters

libmosq_EXPORT void mosquitto_connect_v5_callback_set(     struct  mosquitto  * mosq,     void  (*on_connect)(struct mosquitto *, void *, int, int, const mosquitto_property *props) )

Set the connect callback.  This is called when the broker sends a CONNACK message in response to a connection.

It is valid to set this callback for all MQTT protocol versions.  If it is used with MQTT clients that use MQTT v3.1.1 or earlier, then the `props` argument will always be NULL.

Parameters

Callback Parameters

libmosq_EXPORT void mosquitto_disconnect_callback_set(     struct  mosquitto  * mosq,     void  (*on_disconnect)(struct mosquitto *, void *, int) )

Set the disconnect callback.  This is called when the broker has received the DISCONNECT command and has disconnected the client.

Parameters

Callback Parameters

libmosq_EXPORT void mosquitto_disconnect_v5_callback_set(     struct  mosquitto  * mosq,     void  (*on_disconnect)(struct mosquitto *, void *, int, const mosquitto_property *props) )

Set the disconnect callback.  This is called when the broker has received the DISCONNECT command and has disconnected the client.

It is valid to set this callback for all MQTT protocol versions.  If it is used with MQTT clients that use MQTT v3.1.1 or earlier, then the `props` argument will always be NULL.

Parameters

Callback Parameters

libmosq_EXPORT void mosquitto_publish_callback_set(     struct  mosquitto  * mosq,     void  (*on_publish)(struct mosquitto *, void *, int) )

Set the publish callback.  This is called when a message initiated with mosquitto_publish has been sent to the broker successfully.

Parameters

Callback Parameters

libmosq_EXPORT void mosquitto_publish_v5_callback_set(     struct  mosquitto  * mosq,     void  (*on_publish)(struct mosquitto *, void *, int, int, const mosquitto_property *props) )

Set the publish callback.  This is called when a message initiated with mosquitto_publish has been sent to the broker.  This callback will be called both if the message is sent successfully, or if the broker responded with an error, which will be reflected in the reason_code parameter.

It is valid to set this callback for all MQTT protocol versions.  If it is used with MQTT clients that use MQTT v3.1.1 or earlier, then the `props` argument will always be NULL.

Parameters

Callback Parameters

libmosq_EXPORT void mosquitto_message_callback_set(     struct  mosquitto  * mosq,     void  (*on_message)(struct mosquitto *, void *, const struct mosquitto_message *) )

Set the message callback.  This is called when a message is received from the broker.

Parameters

Callback Parameters

See Also

mosquitto_message_copy

libmosq_EXPORT void mosquitto_message_v5_callback_set(     struct  mosquitto  * mosq,     void  (*on_message)(struct mosquitto *, void *, const struct mosquitto_message *, const mosquitto_property *props) )

Set the message callback.  This is called when a message is received from the broker.

It is valid to set this callback for all MQTT protocol versions.  If it is used with MQTT clients that use MQTT v3.1.1 or earlier, then the `props` argument will always be NULL.

Parameters

Callback Parameters

See Also

mosquitto_message_copy

libmosq_EXPORT void mosquitto_subscribe_callback_set(     struct  mosquitto  * mosq,     void  (*on_subscribe)(struct mosquitto *, void *, int, int, const int *) )

Set the subscribe callback.  This is called when the broker responds to a subscription request.

Parameters

Callback Parameters

libmosq_EXPORT void mosquitto_subscribe_v5_callback_set(     struct  mosquitto  * mosq,     void  (*on_subscribe)(struct mosquitto *, void *, int, int, const int *, const mosquitto_property *props) )

Set the subscribe callback.  This is called when the broker responds to a subscription request.

It is valid to set this callback for all MQTT protocol versions.  If it is used with MQTT clients that use MQTT v3.1.1 or earlier, then the `props` argument will always be NULL.

Parameters

Callback Parameters

libmosq_EXPORT void mosquitto_unsubscribe_callback_set(     struct  mosquitto  * mosq,     void  (*on_unsubscribe)(struct mosquitto *, void *, int) )

Set the unsubscribe callback.  This is called when the broker responds to a unsubscription request.

Parameters

Callback Parameters

libmosq_EXPORT void mosquitto_unsubscribe_v5_callback_set(     struct  mosquitto  * mosq,     void  (*on_unsubscribe)(struct mosquitto *, void *, int, const mosquitto_property *props) )

Set the unsubscribe callback.  This is called when the broker responds to a unsubscription request.

It is valid to set this callback for all MQTT protocol versions.  If it is used with MQTT clients that use MQTT v3.1.1 or earlier, then the `props` argument will always be NULL.

Parameters

Callback Parameters

libmosq_EXPORT void mosquitto_log_callback_set(     struct  mosquitto  * mosq,     void  (*on_log)(struct mosquitto *, void *, int, const char *) )

Set the logging callback.  This should be used if you want event logging information from the client library.

Callback Parameters

libmosq_EXPORT int mosquitto_socks5_set( struct  mosquitto  * mosq, const  char  * host, int  port, const  char  * username, const  char  * password )

Configure the client to use a SOCKS5 proxy when connecting.  Must be called before connecting.  “None” and “username/password” authentication is supported.

Parameters

libmosq_EXPORT const char *mosquitto_strerror( int  mosq_errno )

Call to obtain a const string description of a mosquitto error number.

Parameters

Returns

A constant string describing the error.

libmosq_EXPORT const char *mosquitto_connack_string( int  connack_code )

Call to obtain a const string description of an MQTT connection result.

Parameters

Returns

A constant string describing the result.

libmosq_EXPORT const char *mosquitto_reason_string( int  reason_code )

Call to obtain a const string description of an MQTT reason code.

Parameters

Returns

A constant string describing the reason.

libmosq_EXPORT int mosquitto_string_to_command( const  char  * str, int  * cmd )

Take a string input representing an MQTT command and convert it to the libmosquitto integer representation.

Parameters

Returns

Example

mosquitto_string_to_command("CONNECT", &cmd);
// cmd == CMD_CONNECT

libmosq_EXPORT int mosquitto_sub_topic_tokenise( const  char  * subtopic, char  *** topics, int  * count )

Tokenise a topic or subscription string into an array of strings representing the topic hierarchy.

For example

subtopic: “a/deep/topic/hierarchy”

Would result in

topics[0] = “a” topics[1] = “deep” topics[2] = “topic” topics[3] = “hierarchy”

and

subtopic: “/a/deep/topic/hierarchy/”

Would result in

topics[0] = NULL topics[1] = “a” topics[2] = “deep” topics[3] = “topic” topics[4] = “hierarchy”

Parameters

Returns

Example

char **topics;
int topic_count;
int i;

mosquitto_sub_topic_tokenise("$SYS/broker/uptime", &topics, &topic_count);

for(i=0; i<token_count; i++){
    printf("%d: %s\n", i, topics[i]);
}

See Also

mosquitto_sub_topic_tokens_free

libmosq_EXPORT int mosquitto_sub_topic_tokens_free( char  *** topics, int  count )

Free memory that was allocated in mosquitto_sub_topic_tokenise.

Parameters

Returns

See Also

mosquitto_sub_topic_tokenise

libmosq_EXPORT int mosquitto_topic_matches_sub( const  char  * sub, const  char  * topic, bool  * result )

Check whether a topic matches a subscription.

For example

foo/bar would match the subscription foo/# or +/bar non/matching would not match the subscription non/+/+

Parameters

Returns

libmosq_EXPORT int mosquitto_topic_matches_sub2( const  char  * sub, size_t  sublen, const  char  * topic, size_t  topiclen, bool  * result )

Check whether a topic matches a subscription.

For example

foo/bar would match the subscription foo/# or +/bar non/matching would not match the subscription non/+/+

Parameters

Returns

libmosq_EXPORT int mosquitto_pub_topic_check( const  char  * topic )

Check whether a topic to be used for publishing is valid.

This searches for + or # in a topic and checks its length.

This check is already carried out in mosquitto_publish and mosquitto_will_set, there is no need to call it directly before them.  It may be useful if you wish to check the validity of a topic in advance of making a connection for example.

Parameters

Returns

See Also

mosquitto_sub_topic_check

libmosq_EXPORT int mosquitto_pub_topic_check2( const  char  * topic, size_t  topiclen )

Check whether a topic to be used for publishing is valid.

This searches for + or # in a topic and checks its length.

This check is already carried out in mosquitto_publish and mosquitto_will_set, there is no need to call it directly before them.  It may be useful if you wish to check the validity of a topic in advance of making a connection for example.

Parameters

Returns

See Also

mosquitto_sub_topic_check

libmosq_EXPORT int mosquitto_sub_topic_check( const  char  * topic )

Check whether a topic to be used for subscribing is valid.

This searches for + or # in a topic and checks that they aren’t in invalid positions, such as with foo/#/bar, foo/+bar or foo/bar#, and checks its length.

This check is already carried out in mosquitto_subscribe and mosquitto_unsubscribe, there is no need to call it directly before them.  It may be useful if you wish to check the validity of a topic in advance of making a connection for example.

Parameters

Returns

See Also

mosquitto_sub_topic_check

libmosq_EXPORT int mosquitto_sub_topic_check2( const  char  * topic, size_t  topiclen )

Check whether a topic to be used for subscribing is valid.

This searches for + or # in a topic and checks that they aren’t in invalid positions, such as with foo/#/bar, foo/+bar or foo/bar#, and checks its length.

This check is already carried out in mosquitto_subscribe and mosquitto_unsubscribe, there is no need to call it directly before them.  It may be useful if you wish to check the validity of a topic in advance of making a connection for example.

Parameters

Returns

See Also

mosquitto_sub_topic_check

libmosq_EXPORT int mosquitto_validate_utf8( const  char  * str, int  len )

Helper function to validate whether a UTF-8 string is valid, according to the UTF-8 spec and the MQTT additions.

Parameters

Returns

libmosq_EXPORT int mosquitto_subscribe_simple(     struct  mosquitto_message  ** messages,     int  msg_count,     bool  want_retained,     const  char  * topic,     int  qos,     const  char  * host,     int  port,     const  char  * client_id,     int  keepalive,     bool  clean_session,     const  char  * username,     const  char  * password,     const struct  libmosquitto_will  * will,     const struct  libmosquitto_tls  * tls )

Helper function to make subscribing to a topic and retrieving some messages very straightforward.

This connects to a broker, subscribes to a topic, waits for msg_count messages to be received, then returns after disconnecting cleanly.

Parameters

Returns

libmosq_EXPORT int mosquitto_subscribe_callback(     int  (*callback)(struct mosquitto *, void *, const struct mosquitto_message *),     void  * userdata,     const  char  * topic,     int  qos,     const  char  * host,     int  port,     const  char  * client_id,     int  keepalive,     bool  clean_session,     const  char  * username,     const  char  * password,     const struct  libmosquitto_will  * will,     const struct  libmosquitto_tls  * tls )

Helper function to make subscribing to a topic and processing some messages very straightforward.

This connects to a broker, subscribes to a topic, then passes received messages to a user provided callback.  If the callback returns a 1, it then disconnects cleanly and returns.

Parameters

Returns

libmosq_EXPORT int mosquitto_property_add_byte( mosquitto_property  ** proplist, int  identifier, uint8_t  value )

Add a new byte property to a property list.

If *proplist == NULL, a new list will be created, otherwise the new property will be appended to the list.

Parameters

Returns

Example

mosquitto_property *proplist = NULL;
mosquitto_property_add_byte(&proplist, MQTT_PROP_PAYLOAD_FORMAT_IDENTIFIER, 1);

libmosq_EXPORT int mosquitto_property_add_int16( mosquitto_property  ** proplist, int  identifier, uint16_t  value )

Add a new int16 property to a property list.

If *proplist == NULL, a new list will be created, otherwise the new property will be appended to the list.

Parameters

Returns

Example

mosquitto_property *proplist = NULL;
mosquitto_property_add_int16(&proplist, MQTT_PROP_RECEIVE_MAXIMUM, 1000);

libmosq_EXPORT int mosquitto_property_add_int32( mosquitto_property  ** proplist, int  identifier, uint32_t  value )

Add a new int32 property to a property list.

If *proplist == NULL, a new list will be created, otherwise the new property will be appended to the list.

Parameters

Returns

Example

mosquitto_property *proplist = NULL;
mosquitto_property_add_int32(&proplist, MQTT_PROP_MESSAGE_EXPIRY_INTERVAL, 86400);

libmosq_EXPORT int mosquitto_property_add_varint( mosquitto_property  ** proplist, int  identifier, uint32_t  value )

Add a new varint property to a property list.

If *proplist == NULL, a new list will be created, otherwise the new property will be appended to the list.

Parameters

Returns

Example

mosquitto_property *proplist = NULL;
mosquitto_property_add_varint(&proplist, MQTT_PROP_SUBSCRIPTION_IDENTIFIER, 1);

libmosq_EXPORT int mosquitto_property_add_binary( mosquitto_property  ** proplist, int  identifier, const  void  * value, uint16_t  len )

Add a new binary property to a property list.

If *proplist == NULL, a new list will be created, otherwise the new property will be appended to the list.

Parameters

Returns

Example

mosquitto_property *proplist = NULL;
mosquitto_property_add_binary(&proplist, MQTT_PROP_AUTHENTICATION_DATA, auth_data, auth_data_len);

libmosq_EXPORT int mosquitto_property_add_string( mosquitto_property  ** proplist, int  identifier, const  char  * value )

Add a new string property to a property list.

If *proplist == NULL, a new list will be created, otherwise the new property will be appended to the list.

Parameters

Returns

Example

mosquitto_property *proplist = NULL;
mosquitto_property_add_string(&proplist, MQTT_PROP_CONTENT_TYPE, "application/json");

libmosq_EXPORT int mosquitto_property_add_string_pair(     mosquitto_property  ** proplist,     int  identifier,     const  char  * name,     const  char  * value )

Add a new string pair property to a property list.

If *proplist == NULL, a new list will be created, otherwise the new property will be appended to the list.

Parameters

Returns

Example

mosquitto_property *proplist = NULL;
mosquitto_property_add_string_pair(&proplist, MQTT_PROP_USER_PROPERTY, "client", "mosquitto_pub");

libmosq_EXPORT int mosquitto_property_identifier(     const  mosquitto_property  * property )

Return the property identifier for a single property.

Parameters

Returns

A valid property identifier on success 0 - on error

libmosq_EXPORT const mosquitto_property *mosquitto_property_next(     const  mosquitto_property  * proplist )

Return the next property in a property list.  Use to iterate over a property list, e.g.:

for(prop = proplist; prop != NULL; prop = mosquitto_property_next(prop)){
 if(mosquitto_property_identifier(prop) == MQTT_PROP_CONTENT_TYPE){
     ...
 }
}

Parameters

Returns

Pointer to the next item in the list NULL, if proplist is NULL, or if there are no more items in the list.

libmosq_EXPORT const mosquitto_property *mosquitto_property_read_byte(     const  mosquitto_property  * proplist,     int  identifier,     uint8_t  * value,     bool  skip_first )

Attempt to read a byte property matching an identifier, from a property list or single property.  This function can search for multiple entries of the same identifier by using the returned value and skip_first.  Note however that it is forbidden for most properties to be duplicated.

If the property is not found, *value will not be modified, so it is safe to pass a variable with a default value to be potentially overwritten:

uint16_t keepalive = 60; // default value
// Get value from property list, or keep default if not found.
mosquitto_property_read_int16(proplist, MQTT_PROP_SERVER_KEEP_ALIVE, &keepalive, false);

Parameters

Returns

A valid property pointer if the property is found NULL, if the property is not found, or proplist is NULL.

Example

// proplist is obtained from a callback
mosquitto_property *prop;
prop = mosquitto_property_read_byte(proplist, identifier, &value, false);
while(prop){
    printf("value: %s\n", value);
    prop = mosquitto_property_read_byte(prop, identifier, &value);
}

libmosq_EXPORT const mosquitto_property *mosquitto_property_read_int16(     const  mosquitto_property  * proplist,     int  identifier,     uint16_t  * value,     bool  skip_first )

Read an int16 property value from a property.

Parameters

Returns

A valid property pointer if the property is found NULL, if the property is not found, or proplist is NULL.

Example

See mosquitto_property_read_byte

libmosq_EXPORT const mosquitto_property *mosquitto_property_read_int32(     const  mosquitto_property  * proplist,     int  identifier,     uint32_t  * value,     bool  skip_first )

Read an int32 property value from a property.

Parameters

Returns

A valid property pointer if the property is found NULL, if the property is not found, or proplist is NULL.

Example

See mosquitto_property_read_byte

libmosq_EXPORT const mosquitto_property *mosquitto_property_read_varint(     const  mosquitto_property  * proplist,     int  identifier,     uint32_t  * value,     bool  skip_first )

Read a varint property value from a property.

Parameters

Returns

A valid property pointer if the property is found NULL, if the property is not found, or proplist is NULL.

Example

See mosquitto_property_read_byte

libmosq_EXPORT const mosquitto_property *mosquitto_property_read_binary(     const  mosquitto_property  * proplist,     int  identifier,     void  ** value,     uint16_t  * len,     bool  skip_first )

Read a binary property value from a property.

On success, value must be free()’d by the application.

Parameters

Returns

A valid property pointer if the property is found NULL, if the property is not found, or proplist is NULL, or if an out of memory condition occurred.

Example

See mosquitto_property_read_byte

libmosq_EXPORT const mosquitto_property *mosquitto_property_read_string(     const  mosquitto_property  * proplist,     int  identifier,     char  ** value,     bool  skip_first )

Read a string property value from a property.

On success, value must be free()’d by the application.

Parameters

Returns

A valid property pointer if the property is found NULL, if the property is not found, or proplist is NULL, or if an out of memory condition occurred.

Example

See mosquitto_property_read_byte

libmosq_EXPORT const mosquitto_property *mosquitto_property_read_string_pair(     const  mosquitto_property  * proplist,     int  identifier,     char  ** name,     char  ** value,     bool  skip_first )

Read a string pair property value pair from a property.

On success, name and value must be free()’d by the application.

Parameters

Returns

A valid property pointer if the property is found NULL, if the property is not found, or proplist is NULL, or if an out of memory condition occurred.

Example

See mosquitto_property_read_byte

libmosq_EXPORT void mosquitto_property_free_all( mosquitto_property  ** properties )

Free all properties from a list of properties.  Frees the list and sets *properties to NULL.

Parameters

Example

mosquitto_properties *properties = NULL;
// Add properties
mosquitto_property_free_all(&properties);

libmosq_EXPORT int mosquitto_property_copy_all( mosquitto_property  ** dest, const  mosquitto_property  * src )

Parameters

Returns

libmosq_EXPORT int mosquitto_property_check_command( int  command, int  identifier )

Check whether a property identifier is valid for the given command.

Parameters

Returns

libmosq_EXPORT int mosquitto_property_check_all(     int  command,     const  mosquitto_property  * properties )

Check whether a list of properties are valid for a particular command, whether there are duplicates, and whether the values are valid where possible.

Note that this function is used internally in the library whenever properties are passed to it, so in basic use this is not needed, but should be helpful to check property lists before the point of using them.

Parameters

Returns

libmosq_EXPORT const char *mosquitto_property_identifier_to_string(     int  identifier )

Return the property name as a string for a property identifier.  The property name is as defined in the MQTT specification, with - as a separator, for example: payload-format-indicator.

Parameters

Returns

A const string to the property name on success NULL on failure

libmosq_EXPORT int mosquitto_string_to_property_info( const  char  * propname, int  * identifier, int  * type )

Parse a property name string and convert to a property identifier and data type.  The property name is as defined in the MQTT specification, with - as a separator, for example: payload-format-indicator.

Parameters

Returns

Example

mosquitto_string_to_property_info("response-topic", &id, &type);
// id == MQTT_PROP_RESPONSE_TOPIC
// type == MQTT_PROP_TYPE_STRING