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 and CRLs override the server's application-group trust store for the channel opened to each discovery server. Each item is shared and immutable; the configuration retains shared ownership.

The registration channel validates the discovery server's certificate with the server's application-group validation options, which check revocation by default (CheckRevocationStatusOffline). A CA-issued discovery-server certificate therefore needs the CRL of every CA in its chain here, or it is refused as revocation-unknown; a self-signed certificate needs none.

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.

std::vector< std::shared_ptr< const ua::X509Crl > > trustedCrls

CRLs issued by the CAs in trustedCertificates.

std::vector< std::shared_ptr< const ua::X509Crl > > issuerCrls

CRLs issued by the CAs in issuerCertificates.

ua::app::DiscoveryTarget

A single discovery endpoint the server registers with.

By default the registration channel is SignAndEncrypt with the strongest SecurityPolicy the discovery server offers for that mode, read from its endpoints each cycle: OPC 10000-4 5.4.5.1 requires a discovery server to refuse RegisterServer over an insecure channel, and the SDK's own LDS answers Bad_SecurityModeInsufficient. None is used only when set explicitly.

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::optional< ua::SecurityPolicyId > securityPolicyId

Security policy 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; always Bad. An Uncertain outcome is reported as Bad_InternalError whose ErrorDetail ("RegistrationAnswerUncertain") has the outcome's code as its cause.
• 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 >) - Interface 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 interface 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). DiscoveryRegistration counts only a Good Result as a registered cycle; an Uncertain one, with or without a RegisterOutcome, is a failed cycle. 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. The code the discovery server answered RegisterServer2 or RegisterServer with is kept on the outcome: a Good subcode, or an Uncertain code with the outcome. A channel or GetEndpoints answer that is not Good is not used: the cycle fails, an Uncertain answer with Bad_InternalError and that code as the cause. 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 ApplicationConfig 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 servers <-> "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(ApplicationConfig applicationConfig, std::vector< ServerInstanceConfig > serverInstances={}, std::vector< ClientInstanceConfig > clientInstances={})

Constructs a process configuration from application defaults and optional instances.

• applicationConfig (ApplicationConfig) - Shared application defaults inherited by every instance.
• serverInstances (std::vector< ServerInstanceConfig >) - Server instances to host; defaults to none.
• clientInstances (std::vector< ClientInstanceConfig >) - 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

ApplicationConfig application

Shared application defaults inherited by every instance.

std::vector< ServerInstanceConfig > servers

Server instances hosted by the process.

std::vector< ClientInstanceConfig > clients

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 explicit override exposing the full server API (not re-wrapped); registration() exposes the driver for status and observer access once start has completed.

Member types

ua::Result< ServerWithDiscovery > CreateResult

The created ServerWithDiscovery on success, or an ErrorDetail on failure.

Static functions

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

Creates the wrapper from an executor, the server's configuration and components, and the discovery configuration.

• 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.
• serverComponents (ua::server::ServerComponents) - The server's crypto provider (required), certificate stores, authenticator, Role configuration and log sink; see ua::server::ServerComponents.
• discoveryConfig (DiscoveryRegistrationConfig) - Configuration for the discovery-registration driver (targets, cadence, backoff, trust override).

Returns: The created wrapper.

CreateResult try_create(boost::asio::any_io_executor executor, ua::server::CreateConfig serverConfig, ua::server::ServerComponents serverComponents, DiscoveryRegistrationConfig discoveryConfig) noexcept

Creates the wrapper, returning a bad CreateResult instead of throwing on failure.

• 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.
• serverComponents (ua::server::ServerComponents) - The server's components; see ua::server::ServerComponents.
• discoveryConfig (DiscoveryRegistrationConfig) - Configuration for the discovery-registration driver.

Returns: The constructed wrapper, or an ErrorDetail on failure. Never throws.

Functions

~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 start_sync()

Starts the server and the discovery driver, blocking until complete.

ua::VoidResult try_start_sync() noexcept

Starts the server and the discovery driver, blocking until complete.

Returns: An empty ua::VoidResult on success, or one carrying an ua::ErrorDetail, with Bad_WouldBlock on a thread of the wrapper's executor and otherwise as start_async. 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 with default ua::server::ShutdownOptions (the server's configured grace period, no reason).

• 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.

void shutdown_async(ua::server::ShutdownOptions options, std::function< void(ua::VoidResult)> done) noexcept

Stops the discovery driver and then shuts the server down with options, as ua::server::Server::shutdown_async does.

• options (ua::server::ShutdownOptions) - The grace period and reason passed to the server's shutdown.
• done (std::function< void(ua::VoidResult)>) - Receives the outcome, as for the overload without options. Never throws.

void shutdown_sync(ua::server::ShutdownOptions options={})

Stops the discovery driver and then shuts the server down, blocking until complete.

• options (ua::server::ShutdownOptions) - The grace period and reason passed to the server's shutdown.

ua::VoidResult try_shutdown_sync(ua::server::ShutdownOptions options={}) noexcept

Stops the discovery driver and then shuts the server down, blocking until complete.

• options (ua::server::ShutdownOptions) - The grace period and reason passed to the server's shutdown.

Returns: An empty ua::VoidResult on success, or one carrying an ua::ErrorDetail, with Bad_WouldBlock on a thread of the wrapper's executor and otherwise as shutdown_async. Never throws.

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

Returns the wrapped server, exposing the full server API.

Returns: The wrapped ua::server::Server (explicit override - not re-wrapped).

DiscoveryRegistration & registration()

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

Returns: The DiscoveryRegistration driver.