Enum PacketReadError 

pub enum PacketReadError {
    InsufficientData,
    InvalidUtf8,
    NullCharacterInString,
    InvalidVariableByteIntegerEncoding,
    IncorrectPacketType,
    UnknownReasonCode,
    InvalidBooleanValue,
    TooManyProperties,
    InvalidQosValue,
    UnsupportedProtocolVersion,
    TooManyRequests,
    InvalidPacketType,
    ConnectionReceive,
    PacketTooLargeForBuffer,
    UnexpectedPropertyIdentifier,
    InvalidRetainHandlingValue,
    InvalidConnectFlags,
    IncorrectPacketLength,
    SubscribeWithoutValidSubscriptionRequest,
    SubackWithoutValidReasonCode,
    UnsubscribeWithoutValidSubscriptionRequest,
    UnsubackWithoutValidReasonCode,
    WillQosSpecifiedWithoutWill,
    WillRetainSpecifiedWithoutWill,
    SubscriptionOptionsReservedBitsNonZero,
}

An error occurring while attempting to read/receive/decode an MQTT packet Can occur at multiple levels:

1. Reading data from a [Connection] - e.g. an IO error occurs in underlying data stream
2. Reading data from a buffer - e.g. running out of data
3. Decoding byte data as expected types, e.g. encountering an invalid boolean encoding (value not 0 or 1)
4. Building a packet structure, e.g. there are too many properties or subscription request to fit in a fixed-length heapless::Vec
5. Validating that packet matches MQTT specification, e.g. “reserved” bits of first header byte are not set to correct values

This does NOT include any errors found to be encoded in the packet itself - as long as these errors are correctly decoded this doesn’t represent a read error. Errors in the packet will be handled at higher layers.

Note that these errors mostly map to [ReasonCode::MalformedPacket] when they result in an error encoded in an MQTT packet, they are intended to provide a more granular description of the error to assist in debugging and error handling. Other errors would not ever be represented in a packet, since they represent errors like a failure to read from the network, etc.

Note that some errors map to a [ReasonCode] other than [ReasonCode::MalformedPacket], for example PacketReadError::UnexpectedPropertyIdentifier may map to [ReasonCode::ProtocolError] in the case where a reason string property is sent in a packet type that should not have such a property, see [MQTT-3.1.2-29] in the specification.

Variants

InsufficientData

No more data was available at a point where the MQTT specification states more data must be present in the packet

InvalidUtf8

Data contained bytes that could not be converted to a valid utf8 string

NullCharacterInString

Data contained bytes that resulted in a utf8 string containing one or more null characters, which are not permitted in MQTT strings

InvalidVariableByteIntegerEncoding

While decoding a variable byte integer, the data did not match possible encodings (e.g. it contained more than 3 bytes with continuation bit set, indicating a total encoded length greater than 4 bytes)

IncorrectPacketType

Data was expected to be of a known packet type, but the first header byte did not match this

UnknownReasonCode

Data contained an unknown reason code

InvalidBooleanValue

Data contained a u8 value that was expected to be 0 (false) or 1 (true), but was some other value

TooManyProperties

Data contained a list of properties longer than the P parameter of a packet, and so overflowed a heapless::Vec

InvalidQosValue

Data contained an encoded [QualityOfService] value which was not a recognised value (Malformed Packet)

UnsupportedProtocolVersion

A Connect packet was decoded which did not contain the expected protocol name (MQTT) and version (5) This can be returned to clients, but it is also acceptable to simply close the network connection, see spec 3.1.2.1 and 3.1.2.2

TooManyRequests

Data contained a list of subscription requests (or suback reason codes) longer than the S parameter of a packet, and so overflowed a heapless::Vec

InvalidPacketType

Data meant to encode a packet type had an invalid value. E.g. first header byte could not be decoded to a [PacketType], or contained invalid values for the “reserved” bits.

ConnectionReceive

Failure to receive via connection

PacketTooLargeForBuffer

Packet was too large to place in provided buffer

UnexpectedPropertyIdentifier

When decoding a property for a packet, encountered a value of the property identifier byte that was not expected in the given context. This may be an id that is completely unknown, or just one that is not expected for the type of packet being decoded.

InvalidRetainHandlingValue

When decoding the “retain handling” subscription option, an invalid value not matching the specification was encountered

InvalidConnectFlags

When decoding connect flags of Connect packet, an invalid value was encountered (Malformed Packet)

IncorrectPacketLength

When decoding a packet, the “remaining length” in the packet header was incorrect - the actual packet format indicates the packet is longer or shorter than header indicates

SubscribeWithoutValidSubscriptionRequest

All Subscribe packets must have at least one subscription request [MQTT-3.8.3-2]

SubackWithoutValidReasonCode

All Suback packets must have at least one reason code, since they are responding to a [Subscription] with at least one subscription request [MQTT-3.8.3-2]

UnsubscribeWithoutValidSubscriptionRequest

All Unsubscribe packets must have at least one subscription request [MQTT-3.10.3-2]

UnsubackWithoutValidReasonCode

All Unsuback packets must have at least one reason code, since they are responding to a [Unsubscribe] with at least one subscription request [MQTT-3.10.3-2]

WillQosSpecifiedWithoutWill

WillRetainSpecifiedWithoutWill

SubscriptionOptionsReservedBitsNonZero

Trait Implementations

impl Clone for PacketReadError

fn clone(&self) -> PacketReadError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PacketReadError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for PacketReadError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Format for PacketReadError

Available on crate feature defmt only.

fn format(&self, f: Formatter<'_>)

Writes the defmt representation of self to fmt.

impl From<PacketReadError> for ClientError

fn from(value: PacketReadError) -> Self

Converts to this type from the input type.

impl From<PacketReadError> for ClientStateError

fn from(value: PacketReadError) -> Self

Converts to this type from the input type.

impl From<Utf8Error> for PacketReadError

fn from(_e: Utf8Error) -> Self

Converts to this type from the input type.

impl PartialEq for PacketReadError

fn eq(&self, other: &PacketReadError) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for PacketReadError

impl StructuralPartialEq for PacketReadError