RPC Communication

[中文]

API Reference

RPC Protocol

Public header: #include "brookesia/service_manager/rpc/protocol.hpp"

Header File

• service/brookesia_service_manager/include/brookesia/service_manager/rpc/protocol.hpp

RPC Connection

Public header: #include "brookesia/service_manager/rpc/connection.hpp"

Header File

• service/brookesia_service_manager/include/brookesia/service_manager/rpc/connection.hpp

Classes

class ServerConnection

Bridges one service’s registries to the RPC server transport.

Public Types

using Responder = std::function<bool(size_t, Response&&)>

Callback used to send an RPC response back to a client connection.

using Notifier = std::function<bool(std::size_t, Notify&&)>

Callback used to push an RPC notification to a client connection.

using RequestHandler = std::function<bool(size_t, std::string&&, std::string&&, FunctionParameterMap&&)>

Optional callback that overrides request handling for custom routing.

Public Functions

inline ServerConnection(std::string name, FunctionRegistry &function_registry, EventRegistry &event_registry)

Construct a server-side connection wrapper for one service.

Parameters

• name – [in] Service name exposed to RPC clients.

• function_registry – [in] Registry used for function calls.

• event_registry – [in] Registry used for event subscriptions and notifications.

inline void set_responder(Responder responder)

Set the responder used for sending RPC responses.

Parameters

responder – [in] Transport callback.

inline void set_notifier(Notifier notifier)

Set the notifier used for sending RPC notifications.

Parameters

notifier – [in] Transport callback.

inline void set_request_handler(RequestHandler request_handler)

Set a custom request handler.

Parameters

request_handler – [in] Custom transport-aware request handler.

inline void activate(bool active)

Enable or disable request handling on this connection.

Parameters

active – [in] true to accept RPC traffic, false to reject it.

std::expected<std::shared_ptr<FunctionResult>, std::string> on_request(std::string &&request_id, size_t connection_id, std::string &&method, FunctionParameterMap &&parameters)

Process an incoming RPC request for this service.

Parameters

• request_id – [in] RPC request id.

• connection_id – [in] Transport connection id.

• method – [in] Requested method name.

• parameters – [in] Method parameters.

Returns

std::expected<std::shared_ptr<FunctionResult>, std::string> Function result on success, or an error.

void on_connection_closed(size_t connection_id)

Clear per-connection subscription state when a client disconnects.

Parameters

connection_id – [in] Closed transport connection id.

bool publish_event(const std::string &event_name, const EventItemMap &event_items)

Publish a service event to subscribed RPC clients.

Parameters

• event_name – [in] Event name to publish.

• event_items – [in] Event payload.

Returns

true if notifications were dispatched successfully.

bool respond_request(size_t connection_id, Response &&response)

Send an RPC response to one client connection.

Parameters

• connection_id – [in] Transport connection id.

• response – [in] Response to send.

Returns

true if the response was handed to the transport.

RPC Data Link Base

Public header: #include "brookesia/service_manager/rpc/data_link_base.hpp"

Header File

• service/brookesia_service_manager/include/brookesia/service_manager/rpc/data_link_base.hpp

Classes

class DataLinkBase

Abstract TCP data-link layer shared by RPC clients and servers.

Subclassed by esp_brookesia::service::rpc::DataLinkClient, esp_brookesia::service::rpc::DataLinkServer

Public Types

using OnDataReceived = std::function<void(const std::string &data, size_t connection_id)>

Callback invoked when a complete payload string is received.

using OnConnectionEstablished = std::function<void(size_t connection_id)>

Callback invoked when a transport connection becomes active.

using OnConnectionClosed = std::function<void(size_t connection_id)>

Callback invoked when a transport connection closes.

Public Functions

inline DataLinkBase(boost::asio::io_context::executor_type executor)

Construct the base transport with an executor.

Parameters

executor – [in] Executor that owns asynchronous I/O operations.

inline void set_on_data_received(OnDataReceived callback)

Set the callback used for incoming payloads.

Parameters

callback – [in] Callback to install.

inline void set_on_connection_established(OnConnectionEstablished callback)

Set the callback used for successful connection establishment.

Parameters

callback – [in] Callback to install.

inline void set_on_connection_closed(OnConnectionClosed callback)

Set the callback used for connection teardown.

Parameters

callback – [in] Callback to install.

Public Static Functions

static inline size_t get_active_global_sockets_count()

Get the number of active sockets across all data-link instances.

Returns

size_t Current global socket count.

static inline size_t get_max_global_sockets_count()

Get the configured global socket cap.

Returns

size_t Maximum number of sockets allowed globally.

static inline bool is_global_sockets_limit_reached()

Check whether the global socket cap has been reached.

Returns

true if no more sockets should be opened.

static inline size_t get_max_active_global_sockets_count()

Get the maximum number of simultaneously active sockets observed.

Returns

size_t Historical peak socket count.

RPC Data Link Client

Public header: #include "brookesia/service_manager/rpc/data_link_client.hpp"

Header File

• service/brookesia_service_manager/include/brookesia/service_manager/rpc/data_link_client.hpp

Classes

class DataLinkClient : public esp_brookesia::service::rpc::DataLinkBase

TCP transport used by RPC clients.

Public Functions

inline DataLinkClient(boost::asio::io_context::executor_type executor)

Construct a client transport on the given executor.

Parameters

executor – [in] Executor used for socket operations.

~DataLinkClient() override

Destructor.

bool connect(const std::string &host, uint16_t port, size_t timeout_ms)

Connect to a remote server.

Parameters

• host – [in] Remote host name or address.

• port – [in] Remote TCP port.

• timeout_ms – [in] Connection timeout in milliseconds.

Returns

true if the connection succeeds.

bool disconnect()

Disconnect the active client connection.

Returns

true if a connection existed and cleanup succeeded.

bool send_data(std::string &&data)

Send one payload over the active connection.

Parameters

data – [in] Framed payload to send.

Returns

true if the send operation was queued successfully.

bool is_connected()

Check whether the client currently has an active connection.

Returns

true if connected.

RPC Data Link Server

Public header: #include "brookesia/service_manager/rpc/data_link_server.hpp"

Header File

• service/brookesia_service_manager/include/brookesia/service_manager/rpc/data_link_server.hpp

Classes

class DataLinkServer : public esp_brookesia::service::rpc::DataLinkBase

TCP transport used by the RPC server to accept multiple clients.

Public Functions

inline explicit DataLinkServer(boost::asio::io_context::executor_type executor, size_t max_connections)

Construct a server transport.

Parameters

• executor – [in] Executor used for socket operations.

• max_connections – [in] Maximum number of concurrent client connections.

~DataLinkServer() override

Destructor.

bool start(uint16_t port, size_t timeout_ms)

Start listening for client connections.

Parameters

• port – [in] Local TCP port.

• timeout_ms – [in] Startup timeout in milliseconds.

Returns

true if the server starts successfully.

void stop()

Stop accepting clients and close all active connections.

bool send_data(size_t connection_id, std::string &&data)

Send one payload to a connected client.

Parameters

• connection_id – [in] Client connection id.

• data – [in] Framed payload to send.

Returns

true if the payload was queued successfully.

size_t get_active_connections_count()

Get the number of currently active client connections.

Returns

size_t Active connection count.

std::vector<size_t> get_active_connection_ids()

Get the ids of all active client connections.

Returns

std::vector<size_t> Snapshot of active connection ids.

inline bool is_running()

Check whether the server transport is currently accepting traffic.

Returns

true if running.

inline size_t get_max_connections_count()

Get the configured maximum number of client connections.

Returns

size_t Connection cap.

inline bool is_connection_limit_reached()

Check whether the local connection cap has been reached.

Returns

true if no more clients should be accepted.

inline size_t get_max_active_connections_count()

Get the peak number of simultaneously active client connections.

Returns

size_t Historical maximum for this server instance.

RPC Client

Public header: #include "brookesia/service_manager/rpc/client.hpp"

Header File

• service/brookesia_service_manager/include/brookesia/service_manager/rpc/client.hpp

Classes

class Client

RPC client used to call service functions and subscribe to service events.

Public Types

using DeinitCallback = std::function<void()>

Callback invoked when the client is deinitialized.

using DisconnectCallback = std::function<void()>

Callback invoked after the transport disconnects.

Public Functions

inline Client(DeinitCallback on_deinit_callback = nullptr)

Construct a client with an optional deinitialization callback.

Parameters

on_deinit_callback – [in] Callback invoked by deinit().

~Client()

Destructor.

bool init(boost::asio::io_context::executor_type executor, DisconnectCallback on_disconnect_callback)

Initialize the client transport on an executor.

Parameters

• executor – [in] Executor used for async socket operations.

• on_disconnect_callback – [in] Callback invoked if the transport disconnects.

Returns

true if initialization succeeds.

void deinit()

Deinitialize the client and release its transport resources.

bool connect(const std::string &host, uint16_t port, uint32_t timeout_ms)

Connect to an RPC server.

Parameters

• host – [in] Remote host name or address.

• port – [in] Remote port.

• timeout_ms – [in] Connection timeout in milliseconds.

Returns

true if the connection succeeds.

void disconnect()

Disconnect from the current RPC server.

std::future<FunctionResult> call_function_async(const std::string &target, const std::string &method, boost::json::object &&params)

Call a remote service function asynchronously.

Parameters

• target – [in] Target service name.

• method – [in] Remote function name.

• params – [in] JSON object containing function parameters.

Returns

std::future<FunctionResult> Future resolved with the call result.

FunctionResult call_function_sync(const std::string &target, const std::string &method, boost::json::object &&params, size_t timeout_ms)

Call a remote service function synchronously.

Parameters

• target – [in] Target service name.

• method – [in] Remote function name.

• params – [in] JSON object containing function parameters.

• timeout_ms – [in] Wait timeout in milliseconds.

Returns

FunctionResult Call result or timeout/error information.

std::string subscribe_event(const std::string &target, const std::string &event_name, EventDispatcher::NotifyCallback callback, size_t timeout_ms)

Subscribe to a remote service event.

Parameters

• target – [in] Target service name.

• event_name – [in] Event name to subscribe to.

• callback – [in] Callback invoked when notifications arrive.

• timeout_ms – [in] RPC timeout in milliseconds.

Returns

std::string Subscription id, or an empty string on failure.

bool unsubscribe_events(const std::string &target, const std::vector<std::string> &subscription_ids, size_t timeout_ms)

Unsubscribe from multiple remote event subscriptions.

Parameters

• target – [in] Target service name.

• subscription_ids – [in] Subscription ids to cancel.

• timeout_ms – [in] RPC timeout in milliseconds.

Returns

true if the unsubscribe request succeeds.

RPC Server

Public header: #include "brookesia/service_manager/rpc/server.hpp"

Header File

• service/brookesia_service_manager/include/brookesia/service_manager/rpc/server.hpp

Classes

class Server

RPC server that exposes registered services over TCP.

Public Functions

inline Server(boost::asio::io_context::executor_type executor, const Config &config = Config())

Construct an RPC server on the given executor.

Parameters

• executor – [in] Executor used for socket operations.

• config – [in] Transport configuration.

~Server()

Destructor.

bool init()

Initialize internal transport resources.

Returns

true if initialization succeeds.

void deinit()

Deinitialize the server and release transport resources.

bool start(uint32_t timeout_ms)

Start listening for RPC clients.

Parameters

timeout_ms – [in] Startup timeout in milliseconds.

Returns

true if the server starts successfully.

void stop()

Stop the RPC server.

bool add_connection(std::shared_ptr<ServerConnection> connection)

Attach a service connection to the server.

Parameters

connection – [in] Service connection wrapper to expose.

Returns

true if the connection is added successfully.

bool remove_connection(const std::string &name)

Remove a service connection by service name.

Parameters

name – [in] Service name to remove.

Returns

true if a matching connection was removed.

std::shared_ptr<ServerConnection> get_connection(const std::string &name)

Get a registered service connection.

Parameters

name – [in] Service name to query.

Returns

std::shared_ptr<ServerConnection> Matching connection, or nullptr.

struct Config

Runtime configuration for the RPC server transport.

Public Members

uint16_t listen_port

TCP port used for listening.

size_t max_connections

Maximum number of simultaneous client connections.