Struct esp_idf_svc::mqtt::client::EspMqttClient

pub struct EspMqttClient<'a> { /* private fields */ }

Implementations

impl EspMqttClient<'static>

pub fn new( url: &str, conf: &MqttClientConfiguration<'_> ) -> Result<(Self, EspMqttConnection), EspError>

where Self: Sized,

pub fn new_cb<F>( url: &str, conf: &MqttClientConfiguration<'_>, callback: F ) -> Result<Self, EspError>

where F: for<'b> FnMut(EspMqttEvent<'b>) + Send + 'static, Self: Sized,

impl<'a> EspMqttClient<'a>

pub unsafe fn new_nonstatic_cb<F>( url: &str, conf: &MqttClientConfiguration<'_>, callback: F ) -> Result<Self, EspError>

where F: for<'b> FnMut(EspMqttEvent<'b>) + Send + 'a, Self: Sized,

Safety

This method - in contrast to method new_generic - allows the user to pass a non-static callback/closure. This enables users to borrow

• in the closure - variables that live on the stack - or more generally - in the same scope where the service is created.

HOWEVER: care should be taken NOT to call core::mem::forget() on the service, as that would immediately lead to an UB (crash). Also note that forgetting the service might happen with Rc and Arc when circular references are introduced: https://github.com/rust-lang/rust/issues/24456

The reason is that the closure is actually sent to a hidden ESP IDF thread. This means that if the service is forgotten, Rust is free to e.g. unwind the stack and the closure now owned by this other thread will end up with references to variables that no longer exist.

The destructor of the service takes care - prior to the service being dropped and e.g. the stack being unwind - to remove the closure from the hidden thread and destroy it. Unfortunately, when the service is forgotten, the un-subscription does not happen and invalid references are left dangling.

This “local borrowing” will only be possible to express in a safe way once/if !Leak types are introduced to Rust (i.e. the impossibility to “forget” a type and thus not call its destructor).

pub fn subscribe( &mut self, topic: &str, qos: QoS ) -> Result<MessageId, EspError>

pub fn unsubscribe(&mut self, topic: &str) -> Result<MessageId, EspError>

pub fn publish( &mut self, topic: &str, qos: QoS, retain: bool, payload: &[u8] ) -> Result<MessageId, EspError>

pub fn enqueue( &mut self, topic: &str, qos: QoS, retain: bool, payload: &[u8] ) -> Result<MessageId, EspError>

pub fn subscribe_cstr( &mut self, topic: &CStr, qos: QoS ) -> Result<MessageId, EspError>

pub fn unsubscribe_cstr(&mut self, topic: &CStr) -> Result<MessageId, EspError>

pub fn publish_cstr( &mut self, topic: &CStr, qos: QoS, retain: bool, payload: &[u8] ) -> Result<MessageId, EspError>

pub fn enqueue_cstr( &mut self, topic: &CStr, qos: QoS, retain: bool, payload: &[u8] ) -> Result<MessageId, EspError>

Trait Implementations

impl<'a> Client for EspMqttClient<'a>

fn subscribe(&mut self, topic: &str, qos: QoS) -> Result<MessageId, Self::Error>

fn unsubscribe(&mut self, topic: &str) -> Result<MessageId, Self::Error>

impl<'a> Drop for EspMqttClient<'a>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a> Enqueue for EspMqttClient<'a>

fn enqueue( &mut self, topic: &str, qos: QoS, retain: bool, payload: &[u8] ) -> Result<MessageId, Self::Error>

impl<'a> ErrorType for EspMqttClient<'a>

type Error = EspError

impl<'a> Publish for EspMqttClient<'a>

fn publish( &mut self, topic: &str, qos: QoS, retain: bool, payload: &[u8] ) -> Result<MessageId, Self::Error>

impl<'a> RawHandle for EspMqttClient<'a>

type Handle = *mut esp_mqtt_client

fn handle(&self) -> Self::Handle

Care should be taken to use the returned ESP-IDF driver raw handle only while the driver is still alive, so as to avoid use-after-free errors.

impl<'a> Send for EspMqttClient<'a>