Reference

# Module `mosquitto`

Lua bindings to libmosquitto

This documentation is partial, and doesn't cover all functionality yet.

## Library functions

version () | Return mosquitto library version.
topic_matches_sub (subscription, topic) | Does a topic match a subscription string?
init () |
cleanup () | Cleanup mosquitto library.
new ([client=nil[, clean_session=true]]) | Create a new mosquitto instance

## Instance functions

destroy () | Destroy context This is called automatically by garbage collection, you shouldn't normally have to call this.
reinitialise ([client=nil[, clean=true]]) | Reinitialise
will_set (topic, payload[, qos=0[, retain=false]]) | Set a Will
will_clear () | Clear a will
login_set ([username=nil[, password=nil]]) | Set login details
tls_set ([cafile=nil[, capath=nil[, certfile=nil[, keyfile=nil]]]]) | Set TLS details This doesn't currently support callbacks for passphrase prompting!
tls_insecure_set (value) | Set TLS insecure flags
tls_psk_set (psk, identity[, ciphers]) | Set TLS PSK options
tls_opts_set (cert[, tls_version=nil[, ciphers=nil]]) | Set TLS options, must be called before connect.
threaded_set (value) | Set/clear threaded flag
option (option, value) | Set client options, normally required before connect.
connect ([host=localhost[, port=1883[, keepalive=60]]]) | Connect to a broker
connect_async ([host=localhost[, port=1883[, keepalive=60]]]) | connect (async)
reconnect () |
disconnect () |
publish (topic, payload[, qos=0[, retain=nil]]) | Publish a message
subscribe (topic[, qos=0]) | Subscribe to a topic
unsubscribe (topic) | Unsubscribe from a topic
loop ([timeout=-1[, max_packets=1]]) | run the loop manually
loop_forever ([timeout=-1[, max_packets=1]]) | run the loop forever, blocking
loop_start () | Start a loop thread
loop_stop () | Stop an existing loop thread
socket () | Get the underlying socket
loop_read ([max_packets=1]) | Handle loop read events manually
loop_write ([max_packets=1]) | Handle loop write events manually
loop_misc () | Handle loop misc events manually
want_write () | Does the library want to write?

## Module Constants

callback_ids | Callback ids
log_types | Log types
option_types | Option types
option_values | Option Values

## Library functions

version ()
  Return mosquitto library version.

  ### Returns:

  string version string "major.minor.revision"

  ### See also:

  mosquitto_lib_version
topic_matches_sub (subscription, topic)
  Does a topic match a subscription string?

  ### Parameters:

  - subscription string eg, blah/+/wop/#
  - topic string to test

  ### Returns:

  boolean result

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_topic_matches_sub
init ()

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_lib_init
cleanup ()
  Cleanup mosquitto library. This is called automatically by garbage collection, you shouldn't normally have to call this.

  ### Returns:

  true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_lib_cleanup
new ([client=nil[, clean_session=true]])
  Create a new mosquitto instance

  ### Parameters:

  - client string id, optional. nil to allow library to generate (default nil)
  - clean_session boolean (default true)

  ### Returns:

  a mosquitto instance

  ### Raises:

  For some out of memory or illegal states, or both nil id and clean session true

  ### See also:

  mosquitto_new

## Instance functions

destroy ()
  Destroy context This is called automatically by garbage collection, you shouldn't normally have to call this.

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_destroy
reinitialise ([client=nil[, clean=true]])
  Reinitialise

  ### Parameters:

  - client string id, nil to allow the library to determine (default nil)
  - clean boolean session. (default true)

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  - mosquitto_reinitialise
  - new
will_set (topic, payload[, qos=0[, retain=false]])
  Set a Will

  ### Parameters:

  - topic string as per mosquitto_will_set
  - payload string as per mosquitto_will_set (but a proper lua string)
  - qos number 0, 1 or 2 (default 0)
  - retain boolean (default false)

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_will_set
will_clear ()
  Clear a will

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_will_clear
login_set ([username=nil[, password=nil]])
  Set login details

  ### Parameters:

  - username string may be nil (default nil)
  - password string may be nil (default nil)

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_username_pw_set
tls_set ([cafile=nil[, capath=nil[, certfile=nil[, keyfile=nil]]]])
  Set TLS details This doesn't currently support callbacks for passphrase prompting!

  ### Parameters:

  - cafile string may be nil (default nil)
  - capath string may be nil (default nil)
  - certfile string may be nil (default nil)
  - keyfile string may be nil (default nil)

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_tls_set
tls_insecure_set (value)
  Set TLS insecure flags

  ### Parameters:

  - value boolean true or false

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_tls_insecure_set
tls_psk_set (psk, identity[, ciphers])
  Set TLS PSK options

  ### Parameters:

  - psk string
  - identity string
  - ciphers string (optional)

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_tls_psk_set
tls_opts_set (cert[, tls_version=nil[, ciphers=nil]])
  Set TLS options, must be called before connect.

  ### Parameters:

  - cert bool true for SSL_VERIFY_PEER, false for SSL_VERIFY_NONE
  - tls_version string nil to use default (default nil)
  - ciphers string nil to use the default set (default nil)

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_tls_opts_set
threaded_set (value)
  Set/clear threaded flag

  ### Parameters:

  - value boolean true or false

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_threaded_set
option (option, value)
  Set client options, normally required before connect. This will call _string_option or _int_option automatically based on the parameters provided.

  ### Parameters:

  - option number code, eg M.OPT_TLS_ALPN or M.OPT_PROTOCOL_VERSION
  - value string_or_number the value of the option to set

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For illegal arguments

  ### See also:

  - mosquitto_string_option
  - mosquitto_int_option
  - option_types
connect ([host=localhost[, port=1883[, keepalive=60]]])
  Connect to a broker

  ### Parameters:

  - host string (default localhost)
  - port number (default 1883)
  - keepalive number in seconds (default 60)

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_connect
connect_async ([host=localhost[, port=1883[, keepalive=60]]])
  connect (async)

  ### Parameters:

  - host string (default localhost)
  - port number (default 1883)
  - keepalive number in seconds (default 60)

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_connect_async
reconnect ()

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_reconnect
disconnect ()

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_disconnect
publish (topic, payload[, qos=0[, retain=nil]])
  Publish a message

  ### Parameters:

  - topic string
  - payload string (may be nil)
  - qos number 0, 1 or 2 (default 0)
  - retain boolean flag (default nil)

  ### Returns:

  ### Or

  number MID can be used for correlation with callbacks

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_publish
subscribe (topic[, qos=0])
  Subscribe to a topic

  ### Parameters:

  - topic string eg "blah/+/json/#"
  - qos number 0, 1 or 2 (default 0)

  ### Returns:

  number MID can be used for correlation with callbacks

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_subscribe
unsubscribe (topic)
  Unsubscribe from a topic

  ### Parameters:

  - topic string to unsubscribe from

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_unsubscribe
loop ([timeout=-1[, max_packets=1]])
  run the loop manually

  ### Parameters:

  - timeout number how long in ms to wait for traffic (-1 for library default) (default -1)
  - max_packets number (default 1)

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_loop
loop_forever ([timeout=-1[, max_packets=1]])
  run the loop forever, blocking

  ### Parameters:

  - timeout number how long in ms to wait for traffic (-1 for library default) (default -1)
  - max_packets number (default 1)

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_loop_forever
loop_start ()
  Start a loop thread

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_loop_start
loop_stop ()
  Stop an existing loop thread

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_loop_stop
socket ()
  Get the underlying socket

  ### Returns:

  number the socket number

  ### Or

  boolean false if the socket was uninitialized

  ### See also:

  mosquitto_socket
loop_read ([max_packets=1])
  Handle loop read events manually

  ### Parameters:

  - max_packets number (default 1)

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_loop_read
loop_write ([max_packets=1])
  Handle loop write events manually

  ### Parameters:

  - max_packets number (default 1)

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_loop_write
loop_misc ()
  Handle loop misc events manually

  ### Returns:

  boolean true

  ### Or

  1. nil
  2. number error code
  3. string error description.

  ### Raises:

  For some out of memory or illegal states

  ### See also:

  mosquitto_loop_misc
want_write ()
  Does the library want to write?

  ### Returns:

  boolean result

  ### See also:

  mosquitto_want_write

## Module Constants

callback_ids
  Callback ids

  ### Fields:

  - ON_CONNECT
  - ON_DISCONNECT
  - ON_PUBLISH
  - ON_MESSAGE
  - ON_SUBSCRIBE
  - ON_UNSUBSCRIBE
  - ON_LOG
log_types
  Log types

  ### Fields:

  - LOG_NONE
  - LOG_INFO
  - LOG_NOTICE
  - LOG_WARNING
  - LOG_ERROR
  - LOG_DEBUG
  - LOG_ALL
option_types
  Option types

  ### Fields:

  - OPT_PROTOCOL_VERSION
  - OPT_SSL_CTX
  - OPT_SSL_CTX_WITH_DEFAULTS
  - OPT_RECEIVE_MAXIMUM
  - OPT_SEND_MAXIMUM
  - OPT_TLS_KEYFORM
  - OPT_TLS_ENGINE
  - OPT_TLS_ENGINE_KPASS_SHA1
  - OPT_TLS_OCSP_REQUIRED
  - OPT_TLS_ALPN

  ### See also:

  option
option_values
  Option Values

  ### Fields:

  - MQTT_PROTOCOL_V31
  - MQTT_PROTOCOL_V311
  - MQTT_PROTOCOL_V5

  ### See also:

  option

generated by LDoc 1.4.6 Last updated 2020-08-19 09:34:21