esphome::api::Connection Class Reference

Drives one logical session with an ESPHome device: TCP connect, optional Noise handshake (via the injected frame helper), HelloRequest/HelloResponse, keepalive pings and inbound message dispatch. More...

#include <connection.hpp>

Public Types
using	MessageHandler = std::function< void(const ProtoMessage &)>
using	RawHandler = std::function< void(std::uint32_t msg_type, ByteView payload)>
using	StateHandler = std::function< void(ConnectionState)>
using	ErrorHandler = std::function< void(std::error_code, const std::string &)>
using	ConnectHandler = std::function< void(std::error_code)>

Public Member Functions
	Connection (Executor &executor, std::unique_ptr< Transport > transport, std::unique_ptr< FrameHelper > frame_helper, ConnectionOptions options)
	~Connection ()
	Connection (const Connection &)=delete
Connection &	operator= (const Connection &)=delete
void	start (const std::string &host, std::uint16_t port, ConnectHandler on_done)
	Connect to host:port, perform the handshake and signal completion via on_done exactly once (empty error_code on success).
void	send (const ProtoMessage &msg) const
	Serialize and send a typed protobuf message.
void	send_raw (std::uint32_t msg_type, ByteView payload) const
	Send a pre-serialized payload under an explicit message type id.
void	on (std::uint32_t msg_type, MessageHandler handler)
	Install a handler for one message id (replaces any previous handler).
void	on_any (MessageHandler handler)
	Install a catch-all handler invoked for every decoded inbound message, after any id-specific handler.
void	on_raw (RawHandler handler)
	Install a handler invoked with the raw bytes of every inbound frame (even messages the registry cannot decode).
void	on_state (StateHandler handler)
	Observe state transitions.
void	on_error (ErrorHandler handler)
	Observe terminal errors (read failure, protocol violation, timeout).
void	disconnect ()
	Begin a graceful disconnect (DisconnectRequest, then close).
ConnectionState	state () const noexcept
const ServerHello &	server_hello () const noexcept
bool	is_connected () const noexcept
std::exception_ptr	last_error () const noexcept
	The exception that caused the most recent failure, if it carried richer type/message information than the connect handler's std::error_code (e.g.

Detailed Description

Drives one logical session with an ESPHome device: TCP connect, optional Noise handshake (via the injected frame helper), HelloRequest/HelloResponse, keepalive pings and inbound message dispatch.

All methods must be invoked on the injected Executor (single-threaded from the connection's point of view). Transports/timers post back onto it.

Member Typedef Documentation

ConnectHandler

using esphome::api::Connection::ConnectHandler = std::function<void(std::error_code)>

ErrorHandler

using esphome::api::Connection::ErrorHandler = std::function<void(std::error_code, const std::string&)>

MessageHandler

using esphome::api::Connection::MessageHandler = std::function<void(const ProtoMessage&)>

RawHandler

using esphome::api::Connection::RawHandler = std::function<void(std::uint32_t msg_type, ByteView payload)>

StateHandler

using esphome::api::Connection::StateHandler = std::function<void(ConnectionState)>

Constructor & Destructor Documentation

Connection() [1/2]

esphome::api::Connection::Connection	(	Executor &	executor,
		std::unique_ptr< Transport >	transport,
		std::unique_ptr< FrameHelper >	frame_helper,
		ConnectionOptions	options
	)

~Connection()

esphome::api::Connection::~Connection

(

)

Connection() [2/2]

esphome::api::Connection::Connection ( const Connection &  )

delete

Member Function Documentation

disconnect()

void esphome::api::Connection::disconnect

(

)

Begin a graceful disconnect (DisconnectRequest, then close).

is_connected()

bool esphome::api::Connection::is_connected ( ) const

inlinenoexcept

last_error()

std::exception_ptr esphome::api::Connection::last_error ( ) const

inlinenoexcept

The exception that caused the most recent failure, if it carried richer type/message information than the connect handler's std::error_code (e.g.

an EncryptionMismatchError or HandshakeError from the handshake). Null when the failure was a plain transport error or no failure occurred.

on()

void esphome::api::Connection::on	(	std::uint32_t	msg_type,
		MessageHandler	handler
	)

Install a handler for one message id (replaces any previous handler).

on_any()

void esphome::api::Connection::on_any

(

MessageHandler

handler

)

Install a catch-all handler invoked for every decoded inbound message, after any id-specific handler.

on_error()

void esphome::api::Connection::on_error

(

ErrorHandler

handler

)

Observe terminal errors (read failure, protocol violation, timeout).

on_raw()

void esphome::api::Connection::on_raw

(

RawHandler

handler

)

Install a handler invoked with the raw bytes of every inbound frame (even messages the registry cannot decode).

Runs before decoding.

on_state()

void esphome::api::Connection::on_state

(

StateHandler

handler

)

Observe state transitions.

operator=()

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

delete

send()

void esphome::api::Connection::send

(

const ProtoMessage &

msg

)

const

Serialize and send a typed protobuf message.

send_raw()

void esphome::api::Connection::send_raw	(	std::uint32_t	msg_type,
		ByteView	payload
	)		const

Send a pre-serialized payload under an explicit message type id.

server_hello()

const ServerHello & esphome::api::Connection::server_hello ( ) const

inlinenoexcept

start()

void esphome::api::Connection::start	(	const std::string &	host,
		std::uint16_t	port,
		ConnectHandler	on_done
	)

Connect to host:port, perform the handshake and signal completion via on_done exactly once (empty error_code on success).

state()

ConnectionState esphome::api::Connection::state ( ) const

inlinenoexcept

---

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

• include/esphome/api/connection/connection.hpp