Application

Application-description and bootstrap types shared by client and server.

ua::app::TrustOverride

Explicit trust material for the LDS registration channel.

When supplied, these certificates override the server's application-group trust store for the channel opened to each discovery server. Each certificate is shared and immutable; the configuration retains shared ownership.

Public attributes

std::vector< std::shared_ptr< const ua::X509Certificate > > trustedCertificates

Certificates trusted to identify the discovery server.

std::vector< std::shared_ptr< const ua::X509Certificate > > issuerCertificates

Intermediate CA certificates used to build the trust chain.

ua::app::DiscoveryTarget

A single discovery endpoint the server registers with.

Public attributes

std::string discoveryUrl

Endpoint URL of the discovery server (LDS) to register with.

ua::MessageSecurityMode messageSecurityMode

Security mode for the registration channel.

std::string securityPolicyUri

Security policy URI for the registration channel.

ua::app::DiscoveryRegistrationConfig

Configuration for the discovery-registration driver.

Public attributes

std::vector< DiscoveryTarget > targets

Discovery servers the driver keeps registrations with.

std::chrono::seconds cadence

Interval between successful re-registration cycles.

std::chrono::seconds backoffInitial

First retry delay after a failed cycle.

std::chrono::seconds backoffCap

Upper bound on the exponential retry backoff.

std::chrono::seconds shutdownDeregisterTimeout

Bound on the final deregister cycle during DiscoveryRegistration::stop_async.

std::optional< TrustOverride > ldsTrustOverride

Trust material for the registration channel; nullopt uses the server's application-group store.

ua::app::DiscoveryRegistrationInfo

Per-target context passed to every observer notification.

Identifies which discovery endpoint a notification concerns and how the most recent registration cycle reached it. A fresh value is constructed for each notification; observers must copy any field they wish to retain beyond the call.

Public attributes

std::string discoveryUrl

Discovery endpoint URL of the target this notification concerns.

bool usingFallbackRegisterServer

True when the cycle used the legacy RegisterServer service instead of RegisterServer2.

ua::app::DiscoveryRegistrationObserver

Observer for the discovery-registration lifecycle of a DiscoveryRegistration driver.

Implementations receive edge-triggered notifications as each target transitions between established, failed, fallback, and deregistered states. The default implementations are no-ops, so a subclass overrides only the events it cares about.

All notifications are posted off the driver's internal strand and may run on an unspecified worker thread; implementations must not block and must not assume any particular thread. Notifications for a single target are delivered in order, but no ordering is guaranteed across different targets. The observer is held by shared_ptr for the lifetime of the registration; see DiscoveryRegistration::set_observer.

DiscoveryRegistration

Functions

DiscoveryRegistrationObserver()=default

~DiscoveryRegistrationObserver()=default

Destroys the observer.

void on_registration_established(const DiscoveryRegistrationInfo &info)

Called when a target's registration is successfully established or renewed.

• info (const DiscoveryRegistrationInfo &) - Target context, including whether the legacy RegisterServer fallback was used.

void on_registration_failed(const DiscoveryRegistrationInfo &info, ua::StatusCode status, std::shared_ptr< const ua::ErrorDetail > detail, std::chrono::steady_clock::time_point nextAttempt)

Called when a registration cycle for a target fails and a retry has been scheduled.

• info (const DiscoveryRegistrationInfo &) - Target context for the failed cycle.
• status (ua::StatusCode) - Status code summarising the failure.
• detail (std::shared_ptr< const ua::ErrorDetail >) - Structured error detail for the failure; may be null when none is available. Ownership is shared and the observer may retain it.
• nextAttempt (std::chrono::steady_clock::time_point) - Steady-clock time point at which the next registration attempt is scheduled, reflecting the current backoff.

void on_registration_fallback(const DiscoveryRegistrationInfo &info)

Called when a target transitions to using the legacy RegisterServer fallback.

• info (const DiscoveryRegistrationInfo &) - Target context; DiscoveryRegistrationInfo::usingFallbackRegisterServer is true.

void on_registration_deregistered(const DiscoveryRegistrationInfo &info)

Called when a target has been deregistered, typically during driver shutdown.

• info (const DiscoveryRegistrationInfo &) - Target context for the deregistered endpoint.

ua::app::DiscoveryRegistration

Strand-serialized driver that keeps a server registered with one or more discovery servers (LDS).

Each configured DiscoveryTarget runs an independent registration flow: an open -> register -> close cycle that repeats at the configured cadence and retries failed cycles with exponential backoff. The driver owns a private strand; every public method posts work to it internally, so callers may invoke from any thread. Lifetime is shared: construct via create and hold the returned shared_ptr. Observer notifications are posted off the strand with weak capture, so the observer must not block.

Static functions

std::shared_ptr< DiscoveryRegistration > create(boost::asio::any_io_executor executor, std::shared_ptr< LdsRegistrar > registrar, ua::RegisteredServer serverIdentity, DiscoveryRegistrationConfig config)

Creates a driver and returns shared ownership of it.

• executor (boost::asio::any_io_executor) - Executor the driver binds its private strand to.
• registrar (std::shared_ptr< LdsRegistrar >) - Seam performing each open -> register -> close cycle; must outlive the driver.
• serverIdentity (ua::RegisteredServer) - Identity advertised to each discovery server.
• config (DiscoveryRegistrationConfig) - Targets, cadence, backoff, and trust configuration.

Returns: Shared owner of the new driver.

Functions

void start_async(std::function< void(ua::VoidResult)> done) noexcept

Starts the registration flows for all configured targets.

• done (std::function< void(ua::VoidResult)>) - Receives the outcome on an unspecified worker thread: a good VoidResult once the flows are started, or one carrying an ErrorDetail on failure. Never throws.

void stop_async(std::function< void(ua::VoidResult)> done) noexcept

Stops the driver and performs a bounded final deregister of every target.

• done (std::function< void(ua::VoidResult)>) - Receives the outcome on an unspecified worker thread: a good VoidResult once the driver has stopped, or one carrying an ErrorDetail on failure. Never throws.

void status_async(std::function< void(std::vector< Status >)> done) noexcept

Retrieves a snapshot of every target's registration status.

• done (std::function< void(std::vector< Status >)>) - Receives one Status per configured target, in target order, on an unspecified worker thread. Never throws.

void set_observer(std::shared_ptr< DiscoveryRegistrationObserver > observer) noexcept

Sets the observer that receives lifecycle notifications.

• observer (std::shared_ptr< DiscoveryRegistrationObserver >) - Observer to notify, or nullptr to clear. Shared ownership is retained.

~DiscoveryRegistration()

Destroys the driver.

ua::app::LdsRegistrar

Performs a single open -> register -> close cycle against one discovery server (LDS).

This is the narrow seam the discovery-registration driver depends on, so the driver's state machine can be exercised without a real socket. One register_async call encapsulates the whole cycle against one DiscoveryTarget. Deregistration is not a separate method: it is a register_async call whose ua::RegisteredServer carries isOnline == false.

Member types

std::function< void(ua::Result< RegisterOutcome >)> RegisterResultCallback

Receives the outcome of a register_async cycle: on success the RegisterOutcome, on failure an ua::ErrorDetail.

Functions

LdsRegistrar()=default

~LdsRegistrar()=default

void register_async(DiscoveryTarget target, ua::RegisteredServer server, std::vector< std::shared_ptr< ua::Structure > > discoveryConfiguration, bool preferFallback, RegisterResultCallback callback) noexcept=0

Runs one open -> register -> close cycle against target.

• target (DiscoveryTarget) - Discovery endpoint to register with.
• server (ua::RegisteredServer) - Fully-populated server registration to publish. isOnline is set by the caller: true registers, false deregisters.
• discoveryConfiguration (std::vector< std::shared_ptr< ua::Structure > >) - mDNS discovery-configuration extensions. Carried by RegisterServer2 and dropped by the RegisterServer (v1) fallback.
• preferFallback (bool) - When true, skips RegisterServer2 and goes straight to RegisterServer.
• callback (RegisterResultCallback) - Receives the outcome. On success the RegisterOutcome reports whether the v1 fallback was used: the implementation falls back from RegisterServer2 to RegisterServer transparently within this one cycle, so a usedFallback of true is the caller's cue to memoise preferFallback for later cycles. On failure the Result carries an ua::ErrorDetail whose status reflects where the cycle failed (open, RegisterServer2, or the fallback RegisterServer). This overload never throws.

ua::app::ClientLdsRegistrar

Client-backed LdsRegistrar that drives each cycle through a long-lived OPC UA client.

Holds a shared ua::client::Client for the registrar's lifetime and uses it to run one open -> register -> close cycle per register_async call.

Functions

ClientLdsRegistrar(std::shared_ptr< ua::client::CoreClient > client) noexcept

Constructs a registrar backed by client.

• client (std::shared_ptr< ua::client::CoreClient >) - Client used to open the registration channel. Retained for the registrar's lifetime; must not be null.

~ClientLdsRegistrar() override

void register_async(DiscoveryTarget target, ua::RegisteredServer server, std::vector< std::shared_ptr< ua::Structure > > discoveryConfiguration, bool preferFallback, RegisterResultCallback callback) noexcept override

Runs one open -> register -> close cycle against target using the held client.

• target (DiscoveryTarget) - Discovery endpoint to register with.
• server (ua::RegisteredServer) - Server registration to publish; isOnline selects registering (true) or deregistering (false).
• discoveryConfiguration (std::vector< std::shared_ptr< ua::Structure > >) - mDNS discovery-configuration extensions, carried by RegisterServer2 and dropped by the RegisterServer (v1) fallback.
• preferFallback (bool) - When true, skips RegisterServer2 and goes straight to RegisterServer.
• callback (RegisterResultCallback) - Receives the outcome: the RegisterOutcome on success or an ua::ErrorDetail on failure. Never throws.

ua::ProcessConfigurationFile

Persisted configuration for a single process.

The file schema is a superset that bundles shared application defaults with the per-instance configuration of every server and client the process hosts. It is the in-memory model loaded from, and stored to, the on-disk JSON document.

Application identity is intentionally not persisted: the durable ApplicationConfiguration captures only the reusable parts, and a fresh application URI is generated when a default file is created (see load_default).

JSON object keys mirror the data-member names with the leading m prefix dropped (for example mServers <-> "Servers"). All persisting and loading operations validate the configuration and throw UaException on a malformed document or invalid configuration.

Member types

OnUnreadableFile (enum)

What load_or_create_and_store_default does with a file it cannot read.

• Fail - Throw, and leave the file exactly as it is.
• RecoverAndPreserve - Rename the unreadable file aside, then write and return the default.

Static functions

ProcessConfigurationFile load(const std::filesystem::path &filename)

Loads and parses a process configuration from the file at filename.

• filename (const std::filesystem::path &) - Path to an existing JSON document.

Returns: The parsed configuration.

ProcessConfigurationFile load(const Stream &stream)

Loads and parses a process configuration from stream.

• stream (const Stream &) - Open, readable stream positioned at the start of the JSON document.

Returns: The parsed configuration.

ProcessConfigurationFile from_json_string(std::string_view json)

Parses a process configuration from a JSON string.

• json (std::string_view) - JSON document text, in either the pretty or compact form produced by to_json_string.

Returns: The parsed configuration.

ProcessConfigurationFile load_default()

Builds the built-in default configuration in memory.

Returns: The default configuration; nothing is written to disk.

std::filesystem::path default_config_file()

Returns the conventional default configuration-file path.

Returns: The relative path ./ProcessConfiguration.json.

ProcessConfigurationFile load_or_create_and_store_default(optional< std::filesystem::path > filename=std::nullopt, OnUnreadableFile onUnreadable=OnUnreadableFile::Fail)

Loads the configuration file, creating and storing the default if it is absent.

• filename (optional< std::filesystem::path >) - Path to use; when empty, falls back to default_config_file.
• onUnreadable (OnUnreadableFile) - What to do with a file that is present but cannot be read or parsed.

Returns: The loaded or newly created configuration.

Functions

ProcessConfigurationFile(const ProcessConfigurationFile &)=default

Copyable; deep-copies all instances.

ProcessConfigurationFile(ProcessConfigurationFile &&) noexcept=default

Movable.

ProcessConfigurationFile & operator=(const ProcessConfigurationFile &)=default

Copy-assignable.

Returns: A reference to this object.

ProcessConfigurationFile & operator=(ProcessConfigurationFile &&) noexcept=default

Move-assignable.

Returns: A reference to this object.

~ProcessConfigurationFile()=default

Destructor; deep-destroys all instances.

ProcessConfigurationFile(ApplicationConfiguration application, std::vector< ServerInstanceConfiguration > servers={}, std::vector< ClientInstanceConfiguration > clients={})

Constructs a process configuration from application defaults and optional instances.

• application (ApplicationConfiguration) - Shared application defaults inherited by every instance.
• servers (std::vector< ServerInstanceConfiguration >) - Server instances to host; defaults to none.
• clients (std::vector< ClientInstanceConfiguration >) - Client instances to host; defaults to none.

void store(const std::filesystem::path &filename) const

Validates the configuration and writes it as JSON to the file at filename.

• filename (const std::filesystem::path &) - Destination path for the JSON document.

void store(Stream &stream) const

Validates the configuration and writes it as JSON to stream.

• stream (Stream &) - Open, writable stream that receives the serialized JSON document. The caller retains ownership of the stream.

std::string to_json_string(bool pretty=true) const

Validates the configuration and serializes it to a JSON string.

• pretty (bool) - When true (the default), emits indented, human-readable JSON; when false, emits a compact single-line document.

Returns: The serialized JSON document.

void validate() const

Validates the whole configuration, including every server and client instance.

Public attributes

ApplicationConfiguration mApplication

Shared application defaults inherited by every instance.

std::vector< ServerInstanceConfiguration > mServers

Server instances hosted by the process.

std::vector< ClientInstanceConfiguration > mClients

Client instances hosted by the process.

ua::app::ServerWithDiscovery

Convenience wrapper pairing a ua::server::Server with a DiscoveryRegistration driver that share a single injected executor.

The wrapper owns both halves and drives their combined lifecycle: start_async brings the server up and, once it has bound, creates and starts the discovery driver that keeps it registered with its configured discovery servers (LDS); shutdown_async tears both down in order. A move-only Pimpl handle whose State address is stable across moves so in-flight async continuations stay valid.

server() is an escape hatch exposing the full server API (not re-wrapped); registration() exposes the driver for status and observer access once start has completed.

Functions

ServerWithDiscovery(boost::asio::any_io_executor executor, ua::server::CreateConfig serverConfig, DiscoveryRegistrationConfig discoveryConfig)

Constructs the wrapper from an executor and the server and discovery configurations.

• executor (boost::asio::any_io_executor) - Executor on which the server and discovery driver run their async work.
• serverConfig (ua::server::CreateConfig) - Configuration used to create the wrapped server.
• discoveryConfig (DiscoveryRegistrationConfig) - Configuration for the discovery-registration driver (targets, cadence, backoff, trust override).

~ServerWithDiscovery()

Destroys the wrapper and both owned halves.

ServerWithDiscovery(ServerWithDiscovery &&) noexcept

Move-constructs the wrapper, transferring ownership of both halves.

ServerWithDiscovery & operator=(ServerWithDiscovery &&) noexcept

Move-assigns the wrapper, transferring ownership of both halves.

Returns: Reference to this wrapper after the move.

void start_async(std::function< void(ua::VoidResult)> done) noexcept

Starts the server and, once it has bound, creates and starts the discovery driver.

• done (std::function< void(ua::VoidResult)>) - Receives the outcome: an empty ua::VoidResult on success, or one carrying an ua::ErrorDetail if the server or driver failed to start. This overload never throws.

void shutdown_async(std::function< void(ua::VoidResult)> done) noexcept

Stops the discovery driver (with a bounded final deregister) and then shuts the server down.

• done (std::function< void(ua::VoidResult)>) - Receives the outcome: an empty ua::VoidResult on success, or one carrying an ua::ErrorDetail on failure. This overload never throws.

ua::server::Server & server() noexcept

Returns the wrapped server, exposing the full server API.

Returns: The wrapped ua::server::Server (escape hatch - not re-wrapped).

DiscoveryRegistration & registration() noexcept

Returns the discovery-registration driver for status and observer access.

Returns: The DiscoveryRegistration driver.