Enum GenericEvent

pub enum GenericEvent<PacketIdType>
where
    PacketIdType: IsPacketId + Serialize + 'static,
{
    NotifyPacketReceived(GenericPacket<PacketIdType>),
    RequestSendPacket {
        packet: GenericPacket<PacketIdType>,
        release_packet_id_if_send_error: Option<PacketIdType>,
    },
    NotifyPacketIdReleased(PacketIdType),
    RequestTimerReset {
        kind: TimerKind,
        duration_ms: u64,
    },
    RequestTimerCancel(TimerKind),
    NotifyError(MqttError),
    RequestClose,
}

Generic MQTT Event - represents events that occur during MQTT operations

This enum captures all events that would traditionally be handled by callbacks in a callback-based MQTT implementation. Instead of using callbacks, this Sans-I/O library returns events that the user application must process.

Events are returned from operations like recv() and send() for the user to process. The user application is responsible for handling each event appropriately, such as sending packets over the network, managing timers, or handling errors.

Type Parameters

• PacketIdType - The type used for packet IDs (typically u16, but can be u32 for extended scenarios)

Examples

use mqtt_protocol_core::mqtt;

match event {
    mqtt::connection::GenericEvent::RequestSendPacket { packet, .. } => {
        // Send the packet over the network
        network.send(&packet.to_bytes());
    },
    mqtt::connection::GenericEvent::RequestTimerReset { kind, duration_ms } => {
        // Set or reset a timer
        timer_manager.set_timer(kind, duration_ms);
    },
    // ... handle other events
}

Variants

NotifyPacketReceived(GenericPacket<PacketIdType>)

Notification that a packet was received and parsed successfully

This event is emitted when the MQTT library has successfully received and parsed an incoming packet. The application should process this packet according to its type and content.

Parameters

• GenericPacket<PacketIdType> - The parsed MQTT packet

RequestSendPacket

Request to send a packet via the underlying transport

This event is emitted when the MQTT library needs to send a packet. The application must send this packet over the network transport. If sending fails and a packet ID is specified in release_packet_id_if_send_error, the application should call release_packet_id() to free the packet ID for reuse.

Fields

• packet - The MQTT packet to send
• release_packet_id_if_send_error - Optional packet ID to release if sending fails

Fields

packet: GenericPacket<PacketIdType>

The MQTT packet that needs to be sent over the network

release_packet_id_if_send_error: Option<PacketIdType>

Packet ID to release if the send operation fails (QoS > 0 packets only)

NotifyPacketIdReleased(PacketIdType)

Notification that a packet ID has been released and is available for reuse

This event is emitted when a packet ID is no longer in use and can be assigned to new outgoing packets. This typically happens when:

• A QoS 1 PUBLISH receives its PUBACK
• A QoS 2 PUBLISH completes its full handshake (PUBLISH -> PUBREC -> PUBREL -> PUBCOMP)
• A QoS 2 PUBLISH receives a PUBREC with an error code, terminating the sequence early
• A SUBSCRIBE receives its SUBACK
• An UNSUBSCRIBE receives its UNSUBACK

Parameters

• PacketIdType - The packet ID that has been released

RequestTimerReset

Request to reset or start a timer

This event is emitted when the MQTT library needs to set up a timer for protocol operations such as keep-alive pings or timeout detection. The application should start or reset the specified timer type with the given duration.

Fields

• kind - The type of timer to reset/start
• duration_ms - Timer duration in milliseconds

Fields

kind: TimerKind

The type of timer that needs to be reset or started

duration_ms: u64

Duration of the timer in milliseconds

RequestTimerCancel(TimerKind)

Request to cancel a timer

This event is emitted when the MQTT library needs to cancel a previously set timer. This typically happens when the timer is no longer needed, such as when a PINGRESP is received before the PINGRESP timeout.

Parameters

• TimerKind - The type of timer to cancel

NotifyError(MqttError)

Notification that an error occurred during processing

This event is emitted when the MQTT library encounters an error that prevents normal operation. The application should handle the error appropriately, which may include logging, reconnection attempts, or user notification.

Note: When handling this error, closing the underlying transport is not required. If the connection needs to be closed, a separate RequestClose event will be emitted.

Parameters

• MqttError - The error that occurred

RequestClose

Request to close the connection

This event is emitted when the MQTT library determines that the connection should be closed. This can happen due to protocol violations, disconnect requests, or other terminal conditions. The application should close the underlying network connection.

Trait Implementations

impl<PacketIdType> Clone for GenericEvent<PacketIdType>

where PacketIdType: IsPacketId + Serialize + 'static + Clone,

fn clone(&self) -> GenericEvent<PacketIdType>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<PacketIdType> Debug for GenericEvent<PacketIdType>

where PacketIdType: IsPacketId + Serialize + 'static,

Debug implementation for GenericEvent

Uses the same JSON formatting as Display for consistent debug output. This ensures that debug output is structured and easily parseable.

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

Formats the value using the given formatter.

impl<PacketIdType> Display for GenericEvent<PacketIdType>

where PacketIdType: IsPacketId + Serialize + 'static,

Display implementation for GenericEvent

Formats the event as a JSON string for human-readable output. This is particularly useful for logging and debugging purposes. If serialization fails, an error message is displayed instead.

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

Formats the value using the given formatter.

impl<PacketIdType> Serialize for GenericEvent<PacketIdType>

where PacketIdType: IsPacketId + Serialize + 'static,

Serialization implementation for GenericEvent

This implementation allows GenericEvent to be serialized to JSON format, which can be useful for logging, debugging, or inter-process communication. Each event variant is serialized with a “type” field indicating the event type.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.