object

mqtt

Portable MQTT 5 client predicates using http_transport_protocol implementations.

Availability:

logtalk_load(mqtt(loader))

Author: Paulo Moura

Version: 1:0:0

Date: 2026-08-08

Compilation flags:

static, context_switching_calls

Imports:

public options

public http_origin_site_helpers

Uses:

byte_order

list

type

url(Representation)

user

Remarks:

(none)

Inherited public predicates:

 check_option/1  check_options/1  default_option/1  default_options/1  option/2  option/3  valid_option/1  valid_options/1

Public predicates

connect/3

Opens a transport connection for an MQTT or MQTT-over-TLS address and completes the MQTT CONNECT/CONNACK exchange.

Compilation flags:

static

Template:

connect(Address,Connection,Options)

Mode and number of proofs:

connect(+atom,--compound,+list) - one_or_error

Exceptions:

Address is a variable:

instantiation_error

Address is neither a variable nor an atom:

type_error(atom,Address)

Address is an atom but not a valid MQTT address:

domain_error(mqtt_address,Address)

The server rejects the MQTT connection:

domain_error(mqtt_connack_reason_code,ReasonCode)

The server response is not a CONNACK packet:

domain_error(mqtt_packet,expected(connack,Packet))

---

connect/4

Opens a transport connection to the given host and port and completes the MQTT CONNECT/CONNACK exchange. The scheme/1 option selects MQTT over TCP or TLS.

Compilation flags:

static

Template:

connect(Host,Port,Connection,Options)

Mode and number of proofs:

connect(+atom,+integer,--compound,+list) - one_or_error

Exceptions:

Host or Port is a variable:

instantiation_error

Host is neither a variable nor an atom:

type_error(atom,Host)

Port is neither a variable nor an integer:

type_error(integer,Port)

Port is a negative integer:

domain_error(non_negative_integer,Port)

The server rejects the MQTT connection:

domain_error(mqtt_connack_reason_code,ReasonCode)

The server response is not a CONNACK packet:

domain_error(mqtt_packet,expected(connack,Packet))

---

disconnect/2

Closes an MQTT transport connection. MQTT DISCONNECT packet exchange will be layered on this transport operation.

Compilation flags:

static

Template:

disconnect(Connection,Options)

Mode and number of proofs:

disconnect(+compound,+list) - one_or_error

Exceptions:

Options is a variable or a partial list:

instantiation_error

Options is neither a variable nor a list:

type_error(list,Options)

An element Option of the list Options is not a valid option:

domain_error(option,Option)

---

connection_alive/1

True if the term is an MQTT connection handle created by this object.

Compilation flags:

static

Template:

connection_alive(Connection)

Mode and number of proofs:

connection_alive(+compound) - zero_or_one

---

packet_type/2

Table of MQTT control packet type names and numeric codes.

Compilation flags:

static

Template:

packet_type(Type,Code)

Mode and number of proofs:

packet_type(?atom,?integer) - zero_or_more

---

reason_code/3

Table of MQTT reason code names and numeric codes by packet type.

Compilation flags:

static

Template:

reason_code(PacketType,Name,Code)

Mode and number of proofs:

reason_code(?atom,?atom,?integer) - zero_or_more

---

publish/4

Publishes a message and waits synchronously for the required MQTT acknowledgement.

Compilation flags:

static

Template:

publish(Connection,Topic,Payload,Options)

Mode and number of proofs:

publish(+compound,+atom,+term,+list) - one_or_error

Exceptions:

Topic is not a valid MQTT topic name:

domain_error(mqtt_topic_name,Topic)

Options contains an invalid packet identifier:

domain_error(mqtt_packet_identifier,PacketIdentifier)

Options contains an invalid QoS value:

domain_error(mqtt_qos,QoS)

The server response is not the expected acknowledgement packet:

domain_error(mqtt_packet,expected(Type-PacketIdentifier,Packet))

---

subscribe/4

Subscribes to topic filters and waits synchronously for the matching SUBACK.

Compilation flags:

static

Template:

subscribe(Connection,TopicFilters,Result,Options)

Mode and number of proofs:

subscribe(+compound,+list,--list,+list) - one_or_error

Exceptions:

TopicFilters is empty:

domain_error(mqtt_subscriptions,[])

An element TopicFilter is not a valid MQTT topic filter:

domain_error(mqtt_topic_filter,TopicFilter)

Options contains invalid subscription options:

domain_error(mqtt_subscription_options,Byte)

The server response is not the expected SUBACK packet:

domain_error(mqtt_packet,expected(suback-PacketIdentifier,Packet))

---

unsubscribe/4

Unsubscribes from topic filters and waits synchronously for the matching UNSUBACK.

Compilation flags:

static

Template:

unsubscribe(Connection,TopicFilters,Result,Options)

Mode and number of proofs:

unsubscribe(+compound,+list,--list,+list) - one_or_error

Exceptions:

TopicFilters is empty:

domain_error(mqtt_topic_filters,[])

An element TopicFilter is not a valid MQTT topic filter:

domain_error(mqtt_topic_filter,TopicFilter)

The server response is not the expected UNSUBACK packet:

domain_error(mqtt_packet,expected(unsuback-PacketIdentifier,Packet))

---

receive/3

Receives the next MQTT packet.

Compilation flags:

static

Template:

receive(Connection,Message,Options)

Mode and number of proofs:

receive(+compound,--compound,+list) - one_or_error

Exceptions:

The connection input ends before a complete packet is read:

domain_error(mqtt_packet_stream,unexpected_end_of_file)

The received bytes do not encode a valid MQTT packet:

domain_error(mqtt_packet,Packet)

---

send_pingreq/1

Sends a PINGREQ packet.

Compilation flags:

static

Template:

send_pingreq(Connection)

Mode and number of proofs:

send_pingreq(+compound) - one_or_error

Exceptions:

The PINGREQ packet cannot be written to the connection output stream:

resource_error(mqtt_packet_stream)

---

ping/2

Sends PINGREQ and waits synchronously for PINGRESP.

Compilation flags:

static

Template:

ping(Connection,Options)

Mode and number of proofs:

ping(+compound,+list) - one_or_error

Exceptions:

The connection input ends before a complete packet is read:

domain_error(mqtt_packet_stream,unexpected_end_of_file)

The server response is not a PINGRESP packet:

domain_error(mqtt_packet,expected(pingresp,Packet))

---

encode_packet/2

Encodes a normalized MQTT packet term.

Compilation flags:

static

Template:

encode_packet(Packet,Bytes)

Mode and number of proofs:

encode_packet(+compound,--list(integer)) - one_or_error

Exceptions:

Packet contains an invalid MQTT field value:

domain_error(mqtt_packet,Packet)

Packet has a packet type that is not yet supported:

resource_error(mqtt_packet_support)

---

decode_packet/2

Decodes bytes into a normalized MQTT packet term.

Compilation flags:

static

Template:

decode_packet(Bytes,Packet)

Mode and number of proofs:

decode_packet(+list(integer),--compound) - one_or_error

Exceptions:

Bytes contains an invalid MQTT packet encoding:

domain_error(mqtt_packet,Bytes)

Bytes contains bytes after the encoded packet:

domain_error(mqtt_packet_trailing_bytes,Rest)

Bytes encodes a packet type that is not yet supported:

resource_error(mqtt_packet_support)

---

Protected predicates

(no local declarations; see entity ancestors if any)

Private predicates

resolve_address/4

Resolves an MQTT address into scheme, host, and port.

Compilation flags:

static

Template:

resolve_address(Address,Scheme,Host,Port)

Mode and number of proofs:

resolve_address(+atom,-atom,-atom,-integer) - one_or_error

Exceptions:

Address is a variable:

instantiation_error

Address is neither a variable nor an atom:

type_error(atom,Address)

Address is an atom but not a valid MQTT address:

domain_error(mqtt_address,Address)

Address contains an invalid authority:

domain_error(mqtt_address_authority,Authority)

---

resolve_transport/3

Resolves an explicit or default transport object for the given MQTT scheme.

Compilation flags:

static

Template:

resolve_transport(Scheme,Transport0,Transport)

Mode and number of proofs:

resolve_transport(+atom,+object_identifier,-object_identifier) - one_or_error

Exceptions:

Transport0 is a variable:

instantiation_error

Transport0 is neither a variable nor an existing object:

existence_error(object,Transport0)

Transport0 does not implement http_transport_protocol:

domain_error(http_transport_protocol_object,Transport0)

Transport0 does not support Scheme:

consistency_error(mqtt_options,scheme(Scheme),transport(Transport0))

---

append_tls_transport/3

Adds connection_transport(tls) to connection options for MQTT-over-TLS unless already specified.

Compilation flags:

static

Template:

append_tls_transport(Scheme,Options,OptionsWithTransport)

Mode and number of proofs:

append_tls_transport(+atom,+list,-list) - one_or_error

---

write_packet/2

Encodes and writes an MQTT packet to a binary output stream.

Compilation flags:

static

Template:

write_packet(Output,Packet)

Mode and number of proofs:

write_packet(+stream,+compound) - one_or_error

Exceptions:

Packet is not a supported normalized MQTT packet:

resource_error(mqtt_packet_support)

Output cannot be written or flushed:

resource_error(mqtt_packet_stream)

---

read_packet/2

Reads and decodes one MQTT packet from a binary input stream.

Compilation flags:

static

Template:

read_packet(Input,Packet)

Mode and number of proofs:

read_packet(+stream,--compound) - one_or_error

Exceptions:

Input ends before a complete packet is read:

domain_error(mqtt_packet_stream,unexpected_end_of_file)

Input contains an invalid MQTT packet encoding:

domain_error(mqtt_packet,Packet)

---

encode_uint8/2

Encodes an unsigned 8-bit integer.

Compilation flags:

static

Template:

encode_uint8(Value,Bytes)

Mode and number of proofs:

encode_uint8(+integer,-list(integer)) - one_or_error

Exceptions:

Value is a variable:

instantiation_error

Value is neither a variable nor an integer:

type_error(integer,Value)

Value is outside the unsigned 8-bit integer range:

domain_error(between(0,255),Value)

---

decode_uint8/3

Decodes an unsigned 8-bit integer.

Compilation flags:

static

Template:

decode_uint8(Bytes,Value,Rest)

Mode and number of proofs:

decode_uint8(+list(integer),-integer,-list(integer)) - one_or_error

Exceptions:

The first element of Bytes is not a byte:

type_error(byte,Byte)

---

encode_uint16/2

Encodes an unsigned 16-bit integer in network byte order.

Compilation flags:

static

Template:

encode_uint16(Value,Bytes)

Mode and number of proofs:

encode_uint16(+integer,-list(integer)) - one_or_error

Exceptions:

Value is a variable:

instantiation_error

Value is neither a variable nor an integer:

type_error(integer,Value)

Value is outside the unsigned 16-bit integer range:

domain_error(between(0,65535),Value)

---

decode_uint16/3

Decodes an unsigned 16-bit integer in network byte order.

Compilation flags:

static

Template:

decode_uint16(Bytes,Value,Rest)

Mode and number of proofs:

decode_uint16(+list(integer),-integer,-list(integer)) - one_or_error

Exceptions:

One of the first two elements of Bytes is not a byte:

type_error(byte,Byte)

---

encode_uint32/2

Encodes an unsigned 32-bit integer in network byte order.

Compilation flags:

static

Template:

encode_uint32(Value,Bytes)

Mode and number of proofs:

encode_uint32(+integer,-list(integer)) - one_or_error

Exceptions:

Value is a variable:

instantiation_error

Value is neither a variable nor an integer:

type_error(integer,Value)

Value is outside the unsigned 32-bit integer range:

domain_error(between(0,4294967295),Value)

---

decode_uint32/3

Decodes an unsigned 32-bit integer in network byte order.

Compilation flags:

static

Template:

decode_uint32(Bytes,Value,Rest)

Mode and number of proofs:

decode_uint32(+list(integer),-integer,-list(integer)) - one_or_error

Exceptions:

One of the first four elements of Bytes is not a byte:

type_error(byte,Byte)

---

encode_varint/2

Encodes an MQTT variable byte integer.

Compilation flags:

static

Template:

encode_varint(Value,Bytes)

Mode and number of proofs:

encode_varint(+integer,-list(integer)) - one_or_error

Exceptions:

Value is a variable:

instantiation_error

Value is neither a variable nor an integer:

type_error(integer,Value)

Value is outside the MQTT variable byte integer range:

domain_error(between(0,268435455),Value)

---

decode_varint/3

Decodes an MQTT variable byte integer, rejecting non-minimal encodings and overflows.

Compilation flags:

static

Template:

decode_varint(Bytes,Value,Rest)

Mode and number of proofs:

decode_varint(+list(integer),-integer,-list(integer)) - one_or_error

Exceptions:

Bytes does not start with a valid, minimally encoded MQTT variable byte integer:

domain_error(mqtt_variable_byte_integer,Consumed)

---

encode_utf8_string/2

Encodes an MQTT UTF-8 encoded string with a two-byte length prefix.

Compilation flags:

static

Template:

encode_utf8_string(String,Bytes)

Mode and number of proofs:

encode_utf8_string(+atom,-list(integer)) - one_or_error

Exceptions:

String is a variable:

instantiation_error

String is neither a variable nor atom:

type_error(atom,String)

String is not a valid MQTT UTF-8 string:

domain_error(mqtt_utf8_string,Codes)

---

decode_utf8_string/3

Decodes an MQTT UTF-8 encoded string with a two-byte length prefix.

Compilation flags:

static

Template:

decode_utf8_string(Bytes,String,Rest)

Mode and number of proofs:

decode_utf8_string(+list(integer),-atom,-list(integer)) - one_or_error

Exceptions:

Bytes does not start with a valid MQTT UTF-8 string:

domain_error(mqtt_utf8_string,Codes)

---

encode_binary_data/2

Encodes MQTT binary data with a two-byte length prefix.

Compilation flags:

static

Template:

encode_binary_data(Data,Bytes)

Mode and number of proofs:

encode_binary_data(+list(integer),-list(integer)) - one_or_error

Exceptions:

Data is not a list of bytes:

type_error(list(byte),Data)

Data is longer than 65535 bytes:

domain_error(between(0,65535),Length)

---

decode_binary_data/3

Decodes MQTT binary data with a two-byte length prefix.

Compilation flags:

static

Template:

decode_binary_data(Bytes,Data,Rest)

Mode and number of proofs:

decode_binary_data(+list(integer),-list(integer),-list(integer)) - one_or_error

Exceptions:

The first two elements of Bytes do not encode a valid length:

type_error(byte,Byte)

---

encode_utf8_string_pair/2

Encodes an MQTT UTF-8 string pair as two MQTT UTF-8 encoded strings.

Compilation flags:

static

Template:

encode_utf8_string_pair(Pair,Bytes)

Mode and number of proofs:

encode_utf8_string_pair(+compound,-list(integer)) - one_or_error

Exceptions:

An element of Pair is not an atom:

type_error(atom,String)

An element of Pair is not a valid MQTT UTF-8 string:

domain_error(mqtt_utf8_string,Codes)

---

decode_utf8_string_pair/3

Decodes an MQTT UTF-8 string pair from two MQTT UTF-8 encoded strings.

Compilation flags:

static

Template:

decode_utf8_string_pair(Bytes,Pair,Rest)

Mode and number of proofs:

decode_utf8_string_pair(+list(integer),-compound,-list(integer)) - one_or_error

Exceptions:

Bytes does not start with two valid MQTT UTF-8 strings:

domain_error(mqtt_utf8_string,Codes)

---

encode_properties/2

Encodes an MQTT property list with its variable byte integer length prefix.

Compilation flags:

static

Template:

encode_properties(Properties,Bytes)

Mode and number of proofs:

encode_properties(+list,-list(integer)) - one_or_error

Exceptions:

Properties is a variable or a partial list:

instantiation_error

Properties is neither a variable nor a list:

type_error(list,Properties)

An element Property is not a supported MQTT property:

domain_error(mqtt_property,Property)

---

decode_properties/3

Decodes an MQTT property list and returns the remaining packet bytes.

Compilation flags:

static

Template:

decode_properties(Bytes,Properties,Rest)

Mode and number of proofs:

decode_properties(+list(integer),-list,-list(integer)) - one_or_error

Exceptions:

Bytes does not contain the declared property bytes:

domain_error(mqtt_properties,Bytes)

Bytes contains an unknown property identifier:

domain_error(mqtt_property_identifier,Identifier)

---

encode_property_list/2

Encodes MQTT properties without the property length prefix.

Compilation flags:

static

Template:

encode_property_list(Properties,Bytes)

Mode and number of proofs:

encode_property_list(+list,-list(integer)) - one_or_error

Exceptions:

An element Property is not a supported MQTT property:

domain_error(mqtt_property,Property)

---

decode_property_list/2

Decodes MQTT properties from a property body byte list.

Compilation flags:

static

Template:

decode_property_list(Bytes,Properties)

Mode and number of proofs:

decode_property_list(+list(integer),-list) - one_or_error

Exceptions:

Bytes contains an unknown property identifier:

domain_error(mqtt_property_identifier,Identifier)

---

encode_property/2

Encodes a single MQTT property.

Compilation flags:

static

Template:

encode_property(Property,Bytes)

Mode and number of proofs:

encode_property(+compound,-list(integer)) - one_or_error

Exceptions:

Property is not a supported MQTT property:

domain_error(mqtt_property,Property)

Property contains an invalid value:

domain_error(mqtt_property_value,Name-Value)

---

decode_property/3

Decodes a single MQTT property.

Compilation flags:

static

Template:

decode_property(Bytes,Property,Rest)

Mode and number of proofs:

decode_property(+list(integer),-compound,-list(integer)) - one_or_error

Exceptions:

Bytes starts with an unknown property identifier:

domain_error(mqtt_property_identifier,Identifier)

Bytes contains an invalid property value:

domain_error(mqtt_property_value,Name-Value)

---

mqtt_property/3

Table of MQTT property names, identifiers, and value types.

Compilation flags:

static

Template:

mqtt_property(Name,Identifier,Type)

Mode and number of proofs:

mqtt_property(?atom,?integer,?atom) - zero_or_more

---

encode_fixed_header/4

Encodes an MQTT fixed header from packet type, flags, and remaining length.

Compilation flags:

static

Template:

encode_fixed_header(Type,Flags,RemainingLength,Bytes)

Mode and number of proofs:

encode_fixed_header(+atom,+integer,+integer,-list(integer)) - one_or_error

Exceptions:

Type is not a supported MQTT packet type:

domain_error(mqtt_packet_type,Type)

Flags is invalid for Type:

domain_error(mqtt_fixed_header_flags,Type-Flags)

RemainingLength is outside the MQTT variable byte integer range:

domain_error(between(0,268435455),RemainingLength)

---

decode_fixed_header/5

Decodes an MQTT fixed header into packet type, flags, remaining length, and remaining bytes.

Compilation flags:

static

Template:

decode_fixed_header(Bytes,Type,Flags,RemainingLength,Rest)

Mode and number of proofs:

decode_fixed_header(+list(integer),-atom,-integer,-integer,-list(integer)) - one_or_error

Exceptions:

Bytes starts with an unsupported MQTT packet type:

domain_error(mqtt_packet_type,Code)

Bytes contains invalid fixed header flags:

domain_error(mqtt_fixed_header_flags,Type-Flags)

Bytes contains an invalid MQTT variable byte integer:

domain_error(mqtt_variable_byte_integer,Consumed)

---

Operators

(none)