服务运行层

[English]

API 参考

服务基类

公共头文件： #include "brookesia/service_manager/service/base.hpp"

Header File

service/brookesia_service_manager/include/brookesia/service_manager/service/base.hpp

Classes

class ServiceBase

Base class for bindable services managed by ServiceManager.

Subclasses expose callable functions and publishable events through the function and event registries owned by the service.

Subclassed by esp_brookesia::agent::Base, esp_brookesia::agent::Manager, esp_brookesia::expression::Emote, esp_brookesia::service::Audio, esp_brookesia::service::CustomService, esp_brookesia::service::NVS, esp_brookesia::service::SNTP, esp_brookesia::service::VideoDecoder, esp_brookesia::service::VideoEncoder, esp_brookesia::service::wifi::Wifi

Public Types

using FunctionHandlerMap = std::map<std::string, FunctionHandler>: Map from function names to service-side handlers.

using FunctionResultHandler = std::function<void(FunctionResult&&)>: Callback invoked with the result of an asynchronous function call.

Public Functions

inline ServiceBase(const Attributes &attributes)

Construct a service with immutable attributes.

参数: attributes – [in] Public metadata and scheduler preferences for the service.

virtual ~ServiceBase(): Virtual destructor.

inline virtual std::vector<FunctionSchema> get_function_schemas()

Get the function schemas list.

Subclasses should override this method to return an array of function schemas

std::vector<FunctionSchema> get_function_schemas() override {
    return {
        {
            "add", "Add numbers", {
                {"a", "First", FunctionValueType::Number},
                {"b", "Second", FunctionValueType::Number}
            }
        },
        {
            "sub", "Subtract", {
                {"a", "First", FunctionValueType::Number},
                {"b", "Second", FunctionValueType::Number}
            }
        }
    };
}

返回: std::vector<FunctionSchema> List of function schemas

inline virtual std::vector<EventSchema> get_event_schemas()

Get the event schemas list.

Subclasses should override this method to return an array of event schemas

std::vector<EventSchema> get_event_schemas() override {
    return {
        {
            "value_change", "Value changed", {
                {"value", "New value", EventItemType::Number}
            }
        }
    };
}

返回: std::vector<EventSchema> List of event schemas

bool call_function_async(const std::string &name, FunctionParameterMap parameters_map, FunctionResultHandler handler = nullptr)

Call a function asynchronously with parameters map (non-blocking)

参数

name – [in] Function name to call
parameters_map – [in] FunctionParameterMap map (key-value pairs)
handler – [in] FunctionResultHandler to handle the result, if not provided, the result will be ignored

返回

true if called successfully, false otherwise

bool call_function_async(const std::string &name, std::vector<FunctionValue> parameters_values, FunctionResultHandler handler = nullptr)

Call a function asynchronously with parameters values (non-blocking)

参数

name – [in] Function name to call
parameters_values – [in] FunctionParameterMap values (ordered array)
handler – [in] FunctionResultHandler to handle the result, if not provided, the result will be ignored

返回

true if called successfully, false otherwise

bool call_function_async(const std::string &name, const boost::json::object &parameters_json, FunctionResultHandler handler = nullptr)

Call a function asynchronously with JSON parameters (non-blocking)

参数

name – [in] Function name to call
parameters_json – [in] FunctionParameterMap in JSON object format
handler – [in] FunctionResultHandler to handle the result, if not provided, the result will be ignored

返回

true if called successfully, false otherwise

FunctionResult call_function_sync(const std::string &name, FunctionParameterMap parameters_map, uint32_t timeout_ms = BROOKESIA_SERVICE_MANAGER_DEFAULT_CALL_FUNCTION_TIMEOUT_MS)

Call a function synchronously with parameters map (blocking with timeout)

参数

name – [in] Function name to call
parameters_map – [in] FunctionParameterMap map (key-value pairs)
timeout_ms – [in] Timeout in milliseconds (default: 100ms)

返回

FunctionResult Result of the function call

FunctionResult call_function_sync(const std::string &name, std::vector<FunctionValue> parameters_values, uint32_t timeout_ms = BROOKESIA_SERVICE_MANAGER_DEFAULT_CALL_FUNCTION_TIMEOUT_MS)

Call a function synchronously with parameters values (blocking with timeout)

参数

name – [in] Function name to call
parameters_values – [in] FunctionParameterMap values (ordered array)
timeout_ms – [in] Timeout in milliseconds (default: 100ms)

返回

FunctionResult Result of the function call

FunctionResult call_function_sync(const std::string &name, const boost::json::object &parameters_json, uint32_t timeout_ms = BROOKESIA_SERVICE_MANAGER_DEFAULT_CALL_FUNCTION_TIMEOUT_MS)

Call a function synchronously with JSON parameters (blocking with timeout)

参数

name – [in] Function name to call
parameters_json – [in] FunctionParameterMap in JSON object format
timeout_ms – [in] Timeout in milliseconds (default: 100ms)

返回

FunctionResult Result of the function call

EventRegistry::SignalConnection subscribe_event(const std::string &event_name, const EventRegistry::SignalSlot &slot)

Subscribe to an event.

参数

event_name – [in] Event name to subscribe
slot – [in] Callback slot to be invoked when event is published

返回

EventRegistry::SignalConnection RAII scoped connection object for managing the subscription, automatically disconnects the subscription when the connection object is destroyed.

inline bool is_initialized() const

Check if the service is initialized.

返回: true if initialized, false otherwise

inline bool is_running() const

Check if the service is running.

返回: true if running, false otherwise

inline bool is_server_connected() const

Check if the service is connected to server.

返回: true if connected, false otherwise

inline const Attributes &get_attributes() const

Get the service attributes.

返回: const Attributes& Reference to service attributes

inline virtual std::string get_call_task_group() const

Get the call task group name.

返回: std::string Call task group name

inline virtual std::string get_event_task_group() const

Get the event task group name.

返回: std::string Event task group name

inline virtual std::string get_request_task_group() const

Get the request task group name.

返回: std::string Request task group name

Public Static Functions

template<typename T> static inline FunctionResult to_function_result(std::expected<T, std::string> result)

Helper function to convert std::expected to FunctionResult.

模板参数: T – Return value type, can be void or any type convertible to FunctionValue
参数: result – [in] std::expected object
返回: FunctionResult Converted result

struct Attributes

Service attributes configuration.

Public Functions

inline bool has_scheduler() const

Check whether a dedicated task scheduler configuration is present.

返回: true if the service should create its own scheduler.

inline const lib_utils::TaskScheduler::StartConfig &get_scheduler_config() const

Get the dedicated task scheduler configuration.

备注

Call this only when has_scheduler() returns true.

返回: const lib_utils::TaskScheduler::StartConfig& Config stored in task_scheduler_config.

Public Members

std::string name: Service name.

std::vector<std::string> dependencies = {}: Optional: List of dependent service names, will be started in order.

std::optional<lib_utils::TaskScheduler::StartConfig> task_scheduler_config = std::nullopt: Optional: Task scheduler configuration. If configured, service request tasks will be scheduled to this scheduler; otherwise, ServiceManager’s scheduler will be used

bool bindable = true: Optional: Whether the service can be bound.

Macros

BROOKESIA_SERVICE_FUNC_HANDLER_0(func_name, func_call)

BROOKESIA_SERVICE_FUNC_HANDLER_1(func_name, param_name, param_type, func_call)

BROOKESIA_SERVICE_FUNC_HANDLER_2(func_name, param1_name, param1_type, param2_name, param2_type, func_call)

BROOKESIA_SERVICE_FUNC_HANDLER_3(func_name, p1_name, p1_type, p2_name, p2_type, p3_name, p3_type, func_call)

服务管理器

公共头文件： #include "brookesia/service_manager/service/manager.hpp"

Header File

service/brookesia_service_manager/include/brookesia/service_manager/service/manager.hpp

Classes

class ServiceBinding

Service binding handle.

RAII wrapper for service binding that automatically releases the service and its dependencies when the binding goes out of scope.

Public Functions

inline bool is_valid() const

Check if the binding is valid.

返回: true if valid and service is running, false otherwise

inline explicit operator bool() const

Explicit conversion to bool.

返回: true if valid, false otherwise

inline std::shared_ptr<ServiceBase> get_service() const

Get the service object.

返回: std::shared_ptr<ServiceBase> Pointer to the service

inline std::shared_ptr<ServiceBase> get_dependency_service(const std::string &name) const

Get a dependency service by name.

参数: name – [in] Dependency service name
返回: std::shared_ptr<ServiceBase> Pointer to the dependency service, or nullptr if not found

void release(): Release the service binding.

class ServiceManager

Service manager singleton.

Manages service lifecycle, dependencies, and RPC communication.

Public Functions

bool init()

Initialize the service manager.

返回: true if initialized successfully, false otherwise

void deinit(): Deinitialize the service manager.

bool start(const lib_utils::TaskScheduler::StartConfig &config = DEFAULT_TASK_SCHEDULER_START_CONFIG)

Start the service manager.

参数: config – [in] Task scheduler start configuration
返回: true if started successfully, false otherwise

void stop(): Stop the service manager.

bool add_service(std::shared_ptr<ServiceBase> service)

Add a service to the service manager.

参数: service – [in] Service to add
返回: true if added successfully, false otherwise

bool remove_service(const std::string &name)

Remove a service by name.

参数: name – [in] Service name
返回: true if removed successfully, false otherwise

ServiceBinding bind(const std::string &name)

Bind a service by name.

参数: name – [in] Service name
返回: ServiceBinding Service binding handle

bool start_rpc_server(const rpc::Server::Config &config = rpc::Server::Config(), uint32_t timeout_ms = 100)

Start the RPC server.

参数

config – [in] RPC server configuration
timeout_ms – [in] Timeout in milliseconds (default: 100ms)

返回

true if started successfully, false otherwise

void stop_rpc_server(): Stop the RPC server.

bool connect_rpc_server_to_services(std::vector<std::string> names = {})

Connect RPC server to services.

参数: names – [in] Service names to connect (empty means all services)
返回: true if connected successfully, false otherwise

bool disconnect_rpc_server_from_services(std::vector<std::string> names = {})

Disconnect RPC server from services.

参数: names – [in] Service names to disconnect (empty means all services)
返回: true if disconnected successfully, false otherwise

std::shared_ptr<rpc::Client> new_rpc_client(const RPC_ClientConfig &config = RPC_ClientConfig())

Create a new RPC client.

参数: config – [in] RPC client configuration
返回: std::shared_ptr<rpc::Client> Shared pointer to the RPC client

FunctionResult call_rpc_function_sync(std::string host, const std::string &service_name, const std::string &function_name, boost::json::object params, uint32_t timeout_ms = BROOKESIA_SERVICE_MANAGER_RPC_CLIENT_CALL_FUNCTION_TIMEOUT_MS, uint16_t port = BROOKESIA_SERVICE_MANAGER_RPC_SERVER_LISTEN_PORT)

Call an RPC function synchronously.

参数

host – [in] Host address
service_name – [in] Service name
function_name – [in] Function name
params – [in] Function parameters in JSON format
timeout_ms – [in] Timeout in milliseconds (default: configured timeout)
port – [in] Server port (default: configured port)

返回

FunctionResult Result of the function call

inline bool is_initialized() const

Check if the service manager is initialized.

返回: true if initialized, false otherwise

inline bool is_running() const

Check if the service manager is running.

返回: true if running, false otherwise

inline bool is_rpc_server_running() const

Check if the RPC server is running.

返回: true if running, false otherwise

inline std::shared_ptr<ServiceBase> get_service(const std::string &name)

Get a service by name.

参数: name – [in] Service name
返回: std::shared_ptr<ServiceBase> Pointer to the service, or nullptr if not found

Public Static Functions

static inline lib_utils::TaskScheduler::StartConfig make_default_task_scheduler_start_config()

Default worker configuration used by start().

The configuration creates two worker threads for service dispatching and uses the module-level scheduling defaults defined in macro_configs.h.

static inline ServiceManager &get_instance()

Get the singleton instance.

返回: ServiceManager& Reference to the singleton instance

struct RPC_ClientConfig

Optional callbacks applied to RPC clients created by the manager.

Public Members

rpc::Client::DisconnectCallback on_disconnect_callback: Called after the RPC transport disconnects.

rpc::Client::DeinitCallback on_deinit_callback: Called when the client is deinitialized.

服务本地运行器

公共头文件： #include "brookesia/service_manager/service/local_runner.hpp"

Header File

service/brookesia_service_manager/include/brookesia/service_manager/service/local_runner.hpp

Classes

class LocalTestRunner

Local service test runner.

A test framework based on TaskScheduler that supports executing test sequences in order, where each test item can specify a start delay and run duration.

Public Functions

bool run_tests(const RunTestsConfig &config, const std::vector<LocalTestItem> &test_items)

Run test sequence.

参数

config – [in] Run tests configuration
test_items – [in] List of test items

返回

true if all tests passed, false otherwise

inline bool run_tests(const std::string &service_name, const std::vector<LocalTestItem> &test_items)

Run test sequence with default configuration.

参数

service_name – [in] Service name to test
test_items – [in] List of test items

返回

true if all tests passed, false otherwise

const std::vector<bool> &get_results() const

Get test results.

返回: const std::vector<bool>& Result of each test item

struct RunTestsConfig