Client-side C++ API for connecting to a ProxyServer daemon.
ProxyAPI is the consumer-facing half of the VLink proxy subsystem. It connects to a running ProxyServer over a security-authenticated DDS channel set and exposes asynchronous callbacks for connection state, error transitions, server heartbeats, per-topic statistics, and (when active) raw payload bytes. The class inherits MessageLoop, so posted tasks, timers, handshake retries, and async control publishes execute inside the inherited loop once run() or async_run() has been started. Incoming DDS/SHM callbacks may still arrive on transport-managed receive threads.
- Roles
- Each instance is constructed with exactly one role.
| Role | Description |
kController | Drives the server: may call send_control() and send_data(). |
kListener | Passive observer only; send_control() / send_data() return false. |
- Inheritance Pattern
- Both
ProxyAPI and ProxyServer derive from MessageLoop. Application code may either embed a ProxyAPI directly or subclass it to centralise callback wiring. MessageLoop
^
|
ProxyAPI <-- this class (publicly inherits MessageLoop)
^
|
MyMonitor : public ProxyAPI
- register_connect_callback()
- register_info_callback()
- register_data_callback()
- Operation Modes
- Selectable by a
kController instance through Control::mode.
| Mode | Value | Description |
kOffline | 0 | Disconnected; server releases all subscriptions. |
kObserveOne | 1 | Observe a single selected topic. |
kObserveAll | 2 | Observe every discovered topic. |
kRecord | 3 | Record every topic in the subscription URL list. |
kPlay | 4 | Playback / injection, usually fed by recorded data. |
kEdit | 5 | Forward data injected by the controller. |
kAuto | 6 | Observe selected topics and accept controller injection. |
kAutoAndObserveAll | 7 | Observe every topic and accept controller injection. |
- Error Codes
| Error | Value | Description |
kNoError | 0 | No error. |
kModeError | 1 | Reserved legacy code for unsupported modes. |
kControlError | 2 | Control ID mismatch with the server. |
kReliableCompError | 3 | reliable setting mismatch between client and server. |
kTcpCompError | 4 | enable_tcp setting mismatch. |
kDirectCompError | 5 | direct setting mismatch. |
kMultiProxyError | 7 | Multiple proxy servers or Time identity mismatch. |
kVersionCompError | 8 | VLink version mismatch between client and server. |
kTokenError | 9 | Handshake refused/empty token, or same-identity token mismatch. |
kUnknownError | 10 | Unknown or unclassified error. |
- Connectivity, Handshake, and Heartbeat
- Internally the API subscribes to the 1-second
Time heartbeat published by ProxyServer. When VLINK_PROXY_ENABLE_HANDSHAKE is non-zero (default), it also runs an RPC handshake against the server's security-authenticated handshake service before any Control may be published; the server replies with a per-process token that the API caches under a dedicated mutex and stamps onto every outgoing Control. A refused or empty token raises kTokenError, while handshake setup/connect/invoke timeouts are treated as channel-not-ready and retried silently. Every incoming heartbeat must come from the same server identity and carry the same token: identity mismatch raises kMultiProxyError, an identity-matching token mismatch raises kTokenError; both paths clear the cached token and retry the handshake. After five consecutive seconds without a heartbeat the connection is declared lost and ConnectCallback fires with connected=false. A kController instance caches and posts an initial kAuto Control at construction and re-sends the last control automatically once the server reconnects; actual publication waits for the loop, handshake, and transport handles to be ready. When the macro is 0, the handshake is bypassed and controls flow without any token field.
- Channel Configuration
direct | Data path | Control / Info / Time / Handshake path |
| false | Server-relayed DDS data channel | DDS (security-enabled) |
| true | Local direct SHM publishers / subscribers | DDS (security-enabled) |
- Version Matching
- When
Config::match_version is true (default) the client cross-checks the server's VLINK_VERSION string at connection time and reports kVersionCompError on mismatch.
- Example (Controller)
api.register_connect_callback([](bool connected) {
if (connected) {
}
});
api.register_info_callback([](const std::vector<vlink::ProxyAPI::Info>& list) {
for (const auto& info : list) {
}
});
api.async_run();
api.send_control(ctrl);
Client-side proxy monitoring and control surface backed by a MessageLoop.
Definition: proxy_api.h:200
@ kObserveOne
Observe a single topic taken from the URL list.
Definition: proxy_api.h:212
@ kController
Definition: proxy_api.h:261
@ kProtobuf
Decode through the Protocol Buffers stack.
@ kSubscriber
Event subscriber (receives broadcasts).
Definition: types.h:115
Construction-time configuration aggregate for ProxyAPI.
Definition: proxy_api.h:360
bool match_version
Reject when the server's VLINK_VERSION differs from this client.
Definition: proxy_api.h:369
int domain_id
DDS domain ID; must match the server's domain_id.
Definition: proxy_api.h:362
std::string dds_impl
DDS implementation: "dds", "ddsc", "ddsr", etc.
Definition: proxy_api.h:363
Role role
Role of this client instance.
Definition: proxy_api.h:361
bool reliable
Use reliable DDS QoS; must match the server.
Definition: proxy_api.h:366
Control message sent from a kController instance to ProxyServer.
Definition: proxy_api.h:324
std::vector< UrlMeta > url_meta_list
Topics to observe / record / inject (mode-dependent).
Definition: proxy_api.h:326
Mode mode
Target operation mode.
Definition: proxy_api.h:325
- 注解
- Only one
ProxyServer should exist on a given DDS domain at a time; reaching two will trigger kMultiProxyError.
send_control() and send_data() return false immediately for kListener instances.
1.9.1