Struct esp_idf_svc::http::server::EspHttpServer

source ·

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

Implementations§

source §

impl<'a> EspHttpServer<'a>

source

pub fn ws_handler<H, E>( &mut self, uri: &str, handler: H, ) -> Result<&mut Self, EspError>
where H: for<'r> Fn(&'r mut EspHttpWsConnection) -> Result<(), E> + Send + Sync + 'a, E: Debug,

Registers a function as the handler for a Websockets URI.

The function will be called every time a Websockets connection is made to that URI, receiving a different EspHttpWsConnection each call.

Note that Websockets functionality is gated behind an SDK flag. See crate::ws

source §

impl EspHttpServer<'static>

source

pub fn new(conf: &Configuration) -> Result<Self, EspIOError>

source §

impl<'a> EspHttpServer<'a>

HTTP server

source

pub unsafe fn new_nonstatic(conf: &Configuration) -> Result<Self, EspIOError>

§Safety

This method - in contrast to method new - allows the user to set non-static callbacks/closures as handlers into the returned EspHttpServer service. 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).

source

pub fn handler_chain<C>(&mut self, chain: C) -> Result<&mut Self, EspError>
where C: EspHttpTraversableChain<'a>,

source

pub unsafe fn handler_chain_nonstatic<C>( &mut self, chain: C, ) -> Result<&mut Self, EspError>
where C: EspHttpTraversableChainNonstatic<'a>,

§Safety

This method - in contrast to method handler_chain - allows the user to pass a chain of non-static callbacks/closures. 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).

source

pub fn handler<H>( &mut self, uri: &str, method: Method, handler: H, ) -> Result<&mut Self, EspError>
where H: for<'r> Handler<EspHttpConnection<'r>> + Send + 'static,

Registers a Handler for a URI and a method (GET, POST, etc).

source

pub unsafe fn handler_nonstatic<H>( &mut self, uri: &str, method: Method, handler: H, ) -> Result<&mut Self, EspError>
where H: for<'r> Handler<EspHttpConnection<'r>> + Send + 'a,

Registers a Handler for a URI and a method (GET, POST, etc).

§Safety

This method - in contrast to method handler - 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).

source

pub fn fn_handler<E, F>( &mut self, uri: &str, method: Method, f: F, ) -> Result<&mut Self, EspError>
where F: for<'r> Fn(Request<&mut EspHttpConnection<'r>>) -> Result<(), E> + Send + 'static, E: Debug,

Registers a function as the handler for the given URI and HTTP method (GET, POST, etc).

The function will be called every time an HTTP client requests that URI (via the appropriate HTTP method), receiving a different Request each call. The Request contains a reference to the underlying EspHttpConnection.

source

pub unsafe fn fn_handler_nonstatic<E, F>( &mut self, uri: &str, method: Method, f: F, ) -> Result<&mut Self, EspError>
where F: for<'r> Fn(Request<&mut EspHttpConnection<'r>>) -> Result<(), E> + Send + 'a, E: Debug,

Registers a function as the handler for the given URI and HTTP method (GET, POST, etc).

The function will be called every time an HTTP client requests that URI (via the appropriate HTTP method), receiving a different Request each call. The Request contains a reference to the underlying EspHttpConnection.

§Safety

This method - in contrast to method fn_handler - 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).