Struct ParameterHandler

Struct Documentation

struct ParameterHandler

Handler for client-initiated parameter operations.

When supplied to a WebSocketServerOptions or RemoteAccessGatewayOptions, this handler takes precedence over the deprecated onGetParameters / onSetParameters callbacks. Registering a handler also automatically advertises the Parameters capability. Subscribe/unsubscribe notifications still go through the onParametersSubscribe / onParametersUnsubscribe callbacks on WebSocketServerCallbacks / RemoteAccessGatewayCallbacks; wire those up separately if you want to be notified.

Both onGet and onSet are required: if a ParameterHandler is provided with only one of these set, WebSocketServer::create / RemoteAccessGateway::create returns FoxgloveError::ValueError. To omit a handler entirely, leave both callbacks unset.

Note

These callbacks are invoked from time-sensitive contexts and must not block. If long-running work is required, the implementation should hand the responder off to another thread and return immediately.

Public Members

std::function<void(uint32_t client_id, std::optional<std::string_view> request_id, const std::vector<std::string_view> &param_names, GetParametersResponder &&responder)> onGet

Callback invoked when a client requests parameters.

Required when a ParameterHandler is registered.

The implementation takes ownership of responder; see GetParametersResponder for the completion contract.

Param client_id:

The requesting client’s ID.

Param request_id:

A request ID unique to this client. May be std::nullopt. When present, the buffer is valid for the duration of this call.

Param param_names:

A list of parameter names to fetch, or empty to request all parameters. The buffer is valid for the duration of this call; if the callback wishes to store these values (e.g. to hand them off to another thread along with the responder), it must copy them out.

Param responder:

The responder used to complete the request.

std::function<void(uint32_t client_id, std::optional<std::string_view> request_id, const std::vector<ParameterView> &params, SetParametersResponder &&responder)> onSet

Callback invoked when a client sets parameters.

Required when a ParameterHandler is registered.

The implementation takes ownership of responder; see SetParametersResponder for the completion contract, the request_id echo behavior, and the implementer’s responsibility to broadcast applied updates to other parameter subscribers.

Param client_id:

The requesting client’s ID.

Param request_id:

A request ID unique to this client. May be std::nullopt. When present, the buffer is valid for the duration of this call.

Param params:

A list of parameter values the client wishes to set. The buffer is valid for the duration of this call; if the callback wishes to store these values (e.g. to hand them off to another thread along with the responder), it must copy them out via ParameterView::clone.

Param responder:

The responder used to complete the request.