esphome::api::FrameHelper Class Reference

Stateful codec sitting between the transport and the connection. More...

#include <frame_helper.hpp>

Inheritance diagram for esphome::api::FrameHelper:

Public Types
using	HandshakeReady = std::function< void()>
using	HandshakeError = std::function< void(const std::string &what)>

Public Member Functions
	FrameHelper ()=default
virtual	~FrameHelper ()=default
	FrameHelper (const FrameHelper &)=delete
FrameHelper &	operator= (const FrameHelper &)=delete
	FrameHelper (FrameHelper &&)=delete
FrameHelper &	operator= (FrameHelper &&)=delete
virtual void	encode (std::uint32_t msg_type, ByteView payload, ByteBuffer &out)=0
	Serialize a message (numeric type id + protobuf payload) to wire bytes, appending them to out.
virtual void	feed (ByteView data)=0
	Append freshly received bytes to the internal reassembly buffer.
virtual FrameStatus	next (std::uint32_t &out_type, ByteView &out_payload)=0
	Try to extract the next complete frame.
virtual bool	needs_handshake () const
	True if the transport requires a handshake before application messages (and before the connection should send HelloRequest).
virtual ByteBuffer	connect_bytes ()
	Bytes to transmit immediately after the TCP connection is established (the client's first handshake flight).
virtual void	set_handshake_handlers (HandshakeReady, HandshakeError)
	Register callbacks fired when the handshake completes or fails.

Detailed Description

Stateful codec sitting between the transport and the connection.

A FrameHelper owns an internal reassembly buffer. The connection feeds it raw bytes as they arrive (feed) and repeatedly calls next to drain whole frames. Outgoing messages are serialized with encode.

Implementations: PlaintextFrameHelper (no encryption) and, when built with Noise support, NoiseFrameHelper.

Member Typedef Documentation

HandshakeError

using esphome::api::FrameHelper::HandshakeError = std::function<void(const std::string& what)>

HandshakeReady

using esphome::api::FrameHelper::HandshakeReady = std::function<void()>

Constructor & Destructor Documentation

FrameHelper() [1/3]

esphome::api::FrameHelper::FrameHelper ( )

default

~FrameHelper()

virtual esphome::api::FrameHelper::~FrameHelper ( )

virtualdefault

FrameHelper() [2/3]

esphome::api::FrameHelper::FrameHelper ( const FrameHelper &  )

delete

FrameHelper() [3/3]

esphome::api::FrameHelper::FrameHelper ( FrameHelper &&  )

delete

Member Function Documentation

connect_bytes()

virtual ByteBuffer esphome::api::FrameHelper::connect_bytes ( )

inlinevirtual

Bytes to transmit immediately after the TCP connection is established (the client's first handshake flight).

Empty for plaintext.

Reimplemented in esphome::api::NoiseFrameHelper.

encode()

virtual void esphome::api::FrameHelper::encode ( std::uint32_t  msg_type, ByteView  payload, ByteBuffer &  out  )

pure virtual

Serialize a message (numeric type id + protobuf payload) to wire bytes, appending them to out.

Implemented in esphome::api::NoiseFrameHelper, and esphome::api::PlaintextFrameHelper.

feed()

virtual void esphome::api::FrameHelper::feed ( ByteView  data )

pure virtual

Append freshly received bytes to the internal reassembly buffer.

Implemented in esphome::api::NoiseFrameHelper, and esphome::api::PlaintextFrameHelper.

needs_handshake()

virtual bool esphome::api::FrameHelper::needs_handshake ( ) const

inlinevirtual

True if the transport requires a handshake before application messages (and before the connection should send HelloRequest).

Reimplemented in esphome::api::NoiseFrameHelper.

next()

virtual FrameStatus esphome::api::FrameHelper::next ( std::uint32_t &  out_type, ByteView &  out_payload  )

pure virtual

Try to extract the next complete frame.

On FrameStatus::Ok, out_type is the message type id and out_payload is a view of the protobuf payload that stays valid only until the next call to feed or next. On NeedMore nothing was consumed.

Throws ProtocolError on a malformed or oversized frame.

Implemented in esphome::api::NoiseFrameHelper, and esphome::api::PlaintextFrameHelper.

operator=() [1/2]

FrameHelper & esphome::api::FrameHelper::operator= ( const FrameHelper &  )

delete

operator=() [2/2]

FrameHelper & esphome::api::FrameHelper::operator= ( FrameHelper &&  )

delete

set_handshake_handlers()

virtual void esphome::api::FrameHelper::set_handshake_handlers ( HandshakeReady  , HandshakeError    )

inlinevirtual

Register callbacks fired when the handshake completes or fails.

next consumes handshake frames internally and invokes these.

Reimplemented in esphome::api::NoiseFrameHelper.

---

The documentation for this class was generated from the following file:

• include/esphome/api/frame/frame_helper.hpp