proxy_api.h File Reference

Client-side VLink proxy monitoring and control API. More...

#include <cstdint>
#include <memory>
#include <string>
#include <unordered_set>
#include <vector>
#include "../base/bytes.h"
#include "../base/message_loop.h"
#include "../impl/types.h"

Include dependency graph for proxy_api.h:

Go to the source code of this file.

Classes
class	vlink::ProxyAPI
	Client-side proxy monitoring and control API backed by a MessageLoop. More...
struct	vlink::ProxyAPI::Process
	Describes a VLink node process attached to a topic endpoint. More...
struct	vlink::ProxyAPI::Info
	Statistics and metadata for a single discovered topic endpoint. More...
struct	vlink::ProxyAPI::UrlMeta
	Associates a topic URL with its serialisation type and node role. More...
struct	vlink::ProxyAPI::Control
	Control message sent from a kController client to ProxyServer. More...
struct	vlink::ProxyAPI::Data
	Raw message payload delivered via DataCallback or sent via send_data(). More...
struct	vlink::ProxyAPI::Config
	Construction-time configuration for ProxyAPI. More...

Namespaces
namespace	vlink

Macros
#define	VLINK_PROXY_API_EXPORT   __attribute__((visibility("default")))

Detailed Description

Client-side VLink proxy monitoring and control API.

ProxyAPI provides a C++ interface for connecting to a running ProxyServer daemon. It inherits from MessageLoop, but incoming DDS/SHM callbacks may execute on transport-managed receive threads. The inherited MessageLoop is used for posted tasks and timers when run() or async_run() is started.

Roles

A ProxyAPI instance operates in one of two roles:

Role	Description
kController	Can send Control messages to direct the server's observation/playback.
kListener	Passive observer only; send_control() and send_data() are rejected.

Operation Modes

The proxy server supports eight operation modes, selectable by kController:

Mode	Value	Description
kOffline	0	Disconnected; server releases all subscriptions.
kObserveOne	1	Observe a single selected topic.
kObserveAll	2	Observe all discovered topics.
kRecord	3	Record all topics matching the subscription URL list.
kPlay	4	Replay previously recorded data via the server.
kEdit	5	Edit mode: injects data through the server.
kAuto	6	Auto mode: observe specified topics.
kAutoAndObserveAll	7	Auto + observe all topics simultaneously.

Error Codes

Error	Value	Description
kNoError	0	No error.
kModeError	1	Unsupported mode requested.
kControlError	2	Control ID mismatch with the server.
kReliableCompError	3	reliable setting mismatch between client/server.
kTcpCompError	4	enable_tcp setting mismatch.
kDirectCompError	5	direct setting mismatch.
kMultiProxyError	7	Multiple proxy servers detected on the network.
kVersionCompError	8	VLink version mismatch between client and server.
kUnknownError	9	Unknown error.

Connectivity and Heartbeat

Internally the API subscribes to a 1-second Time heartbeat published by ProxyServer over a security-authenticated DDS channel. If no heartbeat is received for 5 consecutive seconds the connection is declared lost and ConnectCallback is invoked with connected = false. A kController client also sends an initial Control message at construction and re-sends the last control automatically when the server reconnects.

Communication Channels

The transport channels are determined by Config::direct:

direct	Data path	Control/Info/Time path
false	DDS (reliable or best-effort)	DDS (security-enabled)
true	SHM (Iceoryx)	DDS (security-enabled)

Version Matching

When Config::match_version is true (default) the client checks that the server's reported VLINK_VERSION string matches its own at connection time. A mismatch triggers kVersionCompError.

Usage Example (Controller)

vlink::ProxyAPI::Config cfg;
cfg.role        = vlink::ProxyAPI::kController;
cfg.dds_impl    = "dds";
cfg.domain_id   = 0;
cfg.reliable    = false;
cfg.match_version = true;
 
vlink::ProxyAPI api(cfg);
 
api.register_connect_callback([](bool connected) {
  if (connected) {
    // server is online
  }
});
 
api.register_info_callback([](const std::vector<vlink::ProxyAPI::Info>& list) {
  for (const auto& info : list) {
    // info.url, info.freq, info.status, ...
  }
});
 
// Start observing a specific topic
vlink::ProxyAPI::Control ctrl;
ctrl.mode = vlink::ProxyAPI::kObserveOne;
ctrl.url_meta_list.emplace_back(
    {"dds://my/topic", "demo.proto.PointCloud", vlink::SchemaType::kProtobuf, vlink::kSubscriber});
api.send_control(ctrl);
 
api.async_run();      // optional: runs the inherited MessageLoop on a background thread

Note

• Only one ProxyServer should exist on a given DDS domain/channel at a time; connecting to two will trigger kMultiProxyError.
• send_control() and send_data() return false immediately when the role is kListener.

Macro Definition Documentation

VLINK_PROXY_API_EXPORT

#define VLINK_PROXY_API_EXPORT   __attribute__((visibility("default")))