General
Shared utilities: results, error detail, logging, and helpers.
ua::ApplicationIdentity
struct
Static identity an application advertises about itself.
Holds the fixed, build-time identity (product URI, display name, role, and build metadata) used to populate the ApplicationDescription handed to peers. This is distinct from ApplicationConfiguration, which carries the deployment-specific instance settings.
Static functions
ApplicationIdentity load_default()
Returns the SDK's built-in default identity (a server identity with the SDK's product URI and name).
Returns: The SDK's default application identity.
Public attributes
String mProductUri
Manufacturer-assigned product URI identifying the software.
LocalizedText mApplicationName
Human-readable name of the application.
ApplicationType mApplicationType
Role of the application (server, client, ...).
BuildInfo mBuildInfo
Build/version metadata (product, manufacturer, version, build date).
ua::ApplicationConfiguration
struct
Deployment configuration for an OPC UA application instance.
Aggregates the tunable settings that govern an application's protocol timeouts, secure-channel and session lifetimes, execution limits, trust-list locations, and security policy. It is JSON-serializable (to_json_string, store) and reloadable (from_json_string, load), so a deployment can persist and restore its configuration.
The default constructor is deleted: instances are obtained from a factory (load_default, load, from_json_string) so that every configuration starts from a validated baseline.
Static functions
ApplicationConfiguration load(const std::filesystem::path &filename)
Loads a configuration from a JSON file.
filename(const std::filesystem::path &) - Source path.
Returns: The deserialized configuration.
ApplicationConfiguration load(const Stream &stream)
Loads a configuration from a JSON stream.
stream(const Stream &) - Source stream.
Returns: The deserialized configuration.
ApplicationConfiguration from_json_string(std::string_view json)
Deserializes a configuration from a JSON string.
json(std::string_view) - JSON text to parse.
Returns: The deserialized configuration.
ApplicationConfiguration load_default()
Returns a validated configuration populated with the SDK's defaults.
Returns: A default configuration (default trust-list paths under ./pki, standard timeouts) that has already passed validate.
std::filesystem::path default_config_file()
Returns the conventional configuration file path (ApplicationConfiguration.json in the current directory).
Returns: The conventional configuration file path.
Functions
ApplicationConfiguration(const ApplicationConfiguration &)=default
Copy-constructs an independent configuration with the same settings.
ApplicationConfiguration(ApplicationConfiguration &&other) noexcept=default
Move-constructs from other, leaving it in a valid but unspecified state.
other(ApplicationConfiguration &&) - Configuration to move from.
ApplicationConfiguration & operator=(const ApplicationConfiguration &other)=default
Copy-assigns the settings of other.
other(const ApplicationConfiguration &) - Configuration whose settings are copied.
Returns: Reference to this configuration.
ApplicationConfiguration & operator=(ApplicationConfiguration &&other) noexcept=default
Move-assigns from other, leaving it in a valid but unspecified state.
other(ApplicationConfiguration &&) - Configuration to move from.
Returns: Reference to this configuration.
~ApplicationConfiguration()=default
Destroys the configuration, releasing its owned settings.
const ApplicationDescriptionPart & application_description_part() const
Returns the deployment-specific application-description fields (read-only).
Returns: A read-only reference to the application-description fields.
const StackLimits & stack_limits() const
Returns the protocol-stack timeouts and lifetime bounds (read-only).
Returns: A read-only reference to the stack limits.
const FileTrustListConfiguration & file_trust_list_configuration() const
Returns the file-backed trust-list configuration (read-only).
Returns: A read-only reference to the file trust-list configuration.
ApplicationDescriptionPart & application_description_part()
Returns the deployment-specific application-description fields for mutation.
Returns: A mutable reference to the application-description fields.
StackLimits & stack_limits()
Returns the protocol-stack timeouts and lifetime bounds for mutation.
Returns: A mutable reference to the stack limits.
FileTrustListConfiguration & file_trust_list_configuration()
Returns the file-backed trust-list configuration for mutation.
Returns: A mutable reference to the file trust-list configuration.
const ExecutionLimits & execution_limits() const
Returns the execution limits (read-only).
Returns: A read-only reference to the execution limits.
ExecutionLimits & execution_limits()
Returns the execution limits for mutation.
Returns: A mutable reference to the execution limits.
ApplicationDescription construct_application_description(const ApplicationIdentity &identity, span< std::string_view > discoveryUrls) const
Builds the ApplicationDescription advertised to peers.
identity(const ApplicationIdentity &) - Build-time identity supplying name, type, and product URI.discoveryUrls(span< std::string_view >) - Discovery endpoint URLs to advertise; copied into the result.
Returns: The assembled application description.
void store(const std::filesystem::path &filename) const
Serializes this configuration as pretty-printed JSON to a file.
filename(const std::filesystem::path &) - Destination path; created or truncated.
void store(Stream &stream) const
Serializes this configuration as pretty-printed JSON to a stream.
stream(Stream &) - Sink to which the JSON bytes are written.
std::string to_json_string(bool pretty=true) const
Serializes this configuration to a JSON string.
pretty(bool) - Whether to pretty-print with indentation; otherwise compact.
Returns: The JSON representation.
void validate() const
Validates the configuration's invariants.
Public attributes
LocaleId mDefaultLocale
Default locale for localized text emitted by the application.
bool mAllowInsecureEndpoints
Whether to expose endpoints with security policy None.
bool mAllowDeprecatedSecurityPolicies
Whether to permit security policies the spec marks deprecated.
ExecutionLimits mExecutionLimits
Limits guarding recursion depth and loop iterations during request processing.
ua::ApplicationOverrides
struct
A set of optional overrides layered on top of an existing ApplicationConfiguration.
Each member is an std::optional: an engaged value replaces the corresponding field in a base configuration, while a disengaged value leaves the base field untouched. This allows a partial configuration (for example loaded from a deployment-specific JSON file) to amend a fully formed base configuration without restating every field. Apply the overrides with apply_overrides.
JSON keys align with the member names with the leading m prefix dropped (for example mDefaultLocale <-> "DefaultLocale").
apply_overrides
Static functions
ApplicationOverrides from_json_string(std::string_view json)
Parses an ApplicationOverrides from a JSON string.
json(std::string_view) - JSON text produced by to_json_string, or authored to the same schema.
Returns: The parsed overrides.
Functions
std::string to_json_string(bool pretty=true) const
Serialises these overrides to a JSON string.
pretty(bool) - If true, produce human-readable, indented JSON; otherwise produce a compact single-line form.
Returns: The JSON representation of these overrides.
Public attributes
std::optional< ApplicationConfiguration::ApplicationDescriptionPart > mApplicationDescriptionPart
Override for the application-description part of the configuration, if set.
std::optional< ApplicationConfiguration::StackLimits > mStackLimits
Override for the stack/protocol limits and timeouts, if set.
std::optional< ApplicationConfiguration::FileTrustListConfiguration > mFileTrustListConfiguration
Override for the file-backed trust-list configuration, if set.
std::optional< LocaleId > mDefaultLocale
Override for the default locale identifier, if set.
std::optional< bool > mAllowInsecureEndpoints
Override for whether endpoints without security are permitted, if set.
std::optional< bool > mAllowDeprecatedSecurityPolicies
Override for whether deprecated security policies are permitted, if set.
std::optional< size_t > mDecodeWorkLimit
Override for the maximum node/edge work allowed while decoding, if set.
std::optional< size_t > mDecodeRecursionDepthLimit
Override for the maximum live recursion depth allowed while decoding, if set.
std::optional< size_t > mInstantiationDepthLimit
Override for the maximum logical descent allowed while instantiating, if set.
std::optional< size_t > mLoopLimit
Override for the maximum iteration count allowed while decoding, if set.
ua::DiagnosticDecodeOptions
struct
Policy applied while decoding a wire DiagnosticInfo into an ErrorDetail chain.
The defaults reproduce the historical behaviour (no depth cap, bare SymbolicId as the code) so existing callers are byte-identical; the client-side DiagnosticInfoDecoder tightens them per OPC UA client design section 8.15.2.
Public attributes
std::size_t maxChainDepth
Maximum number of decoded chain levels before tail truncation.
bool prefixSymbolicId
When true, a non-empty resolved SymbolicId is recorded as the code with the server.symbolic.
std::function< std::string(std::string_view uri)> namespaceSourceTag
When set, maps a decoded (already string-table-resolved) NamespaceURI to the ErrorDetail source (CL-DIAG-007, section 8.15.2).
ua::EncodingLimits
struct
Resource limits applied when encoding or decoding OPC UA messages.
Bounds the work a single encode/decode may perform, guarding against hostile or malformed input that would otherwise exhaust memory or stack. Groups the structural-work limits (ExecutionLimits, from which the per-operation StackDepth, WorkBudget and LoopLimit budgets are minted) together with the server-side size caps for individual values.
The size caps default to a bounded floor (1 MB string / 16 MB ByteString / 65535 array - matching the server-config defaults) so a bare-constructed decoder is fail-closed against hostile input; populate from an ApplicationConfiguration via make_encoding_limits and override the caps as required. Trusted local input (e.g. NodeSet import) must raise the caps explicitly. This is a plain value type with no internal synchronisation; share a copy per encode/decode operation rather than across threads.
Functions
StackDepth stack_depth() const
Mints a fresh StackDepth work-budget from the configured decode limits.
Returns: A fresh StackDepth budget seeded from the configured decode-work and recursion-depth limits.
WorkBudget work_budget() const
Mints a fresh WorkBudget bounding the nodes and edges of one operation.
Returns: A fresh WorkBudget whose node and edge caps are seeded from the configured decode-work limit.
LoopLimit loop_limit() const
Mints a fresh LoopLimit from the configured loop-iteration limit.
Returns: A fresh LoopLimit seeded from ExecutionLimits::mLoopLimit.
Public attributes
ExecutionLimits mExecution
Structural-work limits (stack-depth and loop budgets) for a single operation.
size_t mMaxStringLength
Maximum length, in bytes, of a single decoded UTF-8 String.
size_t mMaxByteStringLength
Maximum length, in bytes, of a single decoded ByteString.
size_t mMaxArrayLength
Maximum element count of a single decoded array.
ua::ErrorChainView
class
A read-only, outermost-to-innermost view over an ua::ErrorDetail cause chain.
Construct from a ua::StatusCode (the chain hanging off its attached detail) or a borrowed ua::ErrorDetail. The StatusCode overload keeps the chain alive for the view's lifetime, so it is safe over a temporary (e.g. ErrorChainView{result.status_code()}); the ErrorDetail overload borrows and must not outlive the referenced detail.
Functions
ErrorChainView(const StatusCode &status)
status(const StatusCode &) - The status. Views the chain attached to status (empty when the status carries no detail). Holds a shared reference to the chain, so it is safe over a temporary StatusCode.
ErrorChainView(const ErrorDetail &detail)
detail(const ErrorDetail &) - Diagnostic detail associated with the notification. Views the chain rooted at the borrowed detail; the caller owns detail's lifetime.
iterator begin() const
Returns: The requested value. Returns or updates the begin.
iterator end() const
Returns: The requested value. Returns or updates the end.
std::size_t depth() const
Returns: The requested value. The number of links in the chain (0 when there is no attached detail).
ua::NamedValue
struct
A single structured fact attached to one ErrorDetail layer: a controlled key (drawn from the closed vocabulary in ua_error_detail_keys.h) paired with its canonically-rendered string value.
Facts live here, never interpolated into the prose fields (mSummary/mDetail).
Public attributes
std::string key
Controlled context key from the closed vocabulary (ua_error_detail_keys.h).
std::string value
Canonically-rendered string value for that key.
ua::ErrorDetail
struct
Structured error context attached to Result<T> at failure sites.
Designed for developer ergonomics, not wire serialization. The mapping to OPC UA DiagnosticInfo happens at the service response boundary inside DiagnosticCollector (service-internal, never exposed to namespace implementations or user code).
An instance is created once at the failure site, optionally wrapped with cause context by intermediate layers, and consumed at the service boundary. It is shared immutably as shared_ptr<const ErrorDetail> on Result<T>; because it is never mutated after construction it may be read from any thread without synchronization.
Static functions
ErrorDetailBuilder build(std::string code, std::string summary, std::string source)
Opens a fluent, context-bearing builder.
code(std::string) - Machine-readable identifier; stored in ErrorDetail::mCode.summary(std::string) - One-line human-readable description; stored in ErrorDetail::mSummary.source(std::string) - Producing component/layer; stored in ErrorDetail::mSource.
Returns: A builder seeded with the three prose fields, ready for fluent context/cause calls.
Public attributes
std::string mCode
Machine-readable identifier for the error condition.
std::string mSummary
Short, one-line human-readable description suitable for log messages.
std::string mDetail
Extended, multi-line diagnostic information.
std::string mSource
The component or layer that produced this error.
StatusCodeValue mInnerStatus
The underlying status value from the inner/causing operation.
shared_ptr< const ErrorDetail > mCause
Recursive cause chain; null when this is the root cause.
std::vector< NamedValue > mContext
Structured facts for THIS layer (the node id that failed, the operation, the index, the limit, ...) as controlled key -> rendered-value pairs.
ua::ErrorDetailBuilder
class
Fluent builder for an ErrorDetail that carries structured context.
Facts go to context() under a controlled ContextKey; prose stays in the summary/detail string literals. The wrap is lossless: cause() threads the inner status and chain. Converts to unique_ptr<ErrorDetail> (for make_error_detail sites) and to shared_ptr<const ErrorDetail> (so it drops directly into StatusCode{...}, UaException{...} and Result{...} with no terminal).
throwUaException{Status::BadNodeIdUnknown, ErrorDetail::build("NodeIdUnknown","nodenotfound","server.services.read") .context(ContextKeys::sNodeId,nodeId)//NodeIdrenderedcanonically .context(ContextKeys::sOperationIndex,i)};//integerrendered;no
Functions
ErrorDetailBuilder(std::string code, std::string summary, std::string source)
Starts a builder for an ErrorDetail with the three required prose fields set.
code(std::string) - Machine-readable identifier; stored in ErrorDetail::mCode.summary(std::string) - One-line human-readable description; stored in ErrorDetail::mSummary.source(std::string) - Producing component/layer; stored in ErrorDetail::mSource.
ErrorDetailBuilder & detail(std::string extended) &
Sets the extended prose (mDetail).
extended(std::string) - Extended diagnostic prose; stored in ErrorDetail::mDetail.
Returns: *this, for fluent chaining.
ErrorDetailBuilder & context(const ContextKey &key, std::string value) &
Appends one structured fact.
key(const ContextKey &) - Vocabulary constant naming the fact; stored as the wire key.value(std::string) - Canonically-rendered string value for key.
Returns: *this, for fluent chaining.
ErrorDetailBuilder & context(const ContextKey &key, const T &value) &
Appends a structured fact, rendering value to its canonical string via the ADL-found error_detail_render(value) so a NodeId, integer, etc.
key(const ContextKey &) - Vocabulary constant naming the fact; stored as the wire key.value(const T &) - Renderable fact value, converted to its canonical string via error_detail_render.
Returns: *this, for fluent chaining.
ErrorDetailBuilder & cause(StatusCode cause) &
Threads a rich StatusCode cause: lifts its numeric inner status and links its detail chain (mirrors the make_error_detail(.., StatusCode) overload).
cause(StatusCode) - StatusCode supplying the numeric inner status and the cause chain.
Returns: *this, for fluent chaining.
ErrorDetailBuilder & cause(shared_ptr< const ErrorDetail > cause) &
Links an explicit cause chain.
cause(shared_ptr< const ErrorDetail >) - Inner cause to link; stored in ErrorDetail::mCause. May be null.
Returns: *this, for fluent chaining.
operator std::unique_ptr< ErrorDetail >()
Terminal: hands over the built ErrorDetail as an owning unique_ptr.
Returns: The built ErrorDetail as an owning std::unique_ptr.
operator std::shared_ptr< const ErrorDetail >()
Terminal: hands over the built ErrorDetail as a shared_ptr<const ErrorDetail>.
Returns: The built ErrorDetail as a std::shared_ptr<const ErrorDetail>.
ua::ContextKey
class
A single key drawn from the closed ErrorDetail structured-context vocabulary.
Wraps the wire string used as the key in ErrorDetail::mContext. The constructor is private, so the only ContextKey values that exist are the named constants in ContextKeys (its sole friend); an off-vocabulary key including a raw string literal is a compile error. Obtain one by naming a constant, e.g. ua::ContextKeys::sNodeId, and pass it to ErrorDetailBuilder::context.
Functions
constexpr std::string_view value() const noexcept
Returns the underlying wire key string (the literal stored under it in mContext).
Returns: The wire key string; a view over static storage that outlives any caller.
ua::ContextKeys
struct
The controlled vocabulary: the complete, closed set of context keys.
A pure namespace-like scope for the ContextKey constants; deleting the default constructor makes it non-instantiable. Reference a key as ua::ContextKeys::sNodeId (the names below carry the per-key value-format contract).
Static attributes
constexpr ContextKey sNodeAttribute
Attribute of the node being acted on, as the symbolic AttributeId enum name.
constexpr ContextKey sNodeBrowseName
BrowseName of the targeted node, rendered ns:Name (the namespace-0 branch elides the prefix and renders the bare Name).
constexpr ContextKey sNodeId
NodeId of the targeted node, rendered via ua::to_string (the canonical ns=<idx>;i=<id> form; an ExpandedNodeId additionally embeds svr=/nsu=).
constexpr ContextKey sNamespaceIndex
Namespace index that is a fact about the target, decimal.
constexpr ContextKey sNamespaceUri
Namespace URI that is a fact about the target, verbatim.
constexpr ContextKey sNamespaceSourceGeneration
Generation of the NamespaceTable snapshot a translation reads a NodeId's index FROM, decimal.
constexpr ContextKey sNamespaceTargetGeneration
Generation of the NamespaceTable snapshot a translation resolves a URI INTO, decimal.
constexpr ContextKey sTypeActual
Type actually presented, as its symbolic name.
constexpr ContextKey sTypeExpected
Type the operation required, as its symbolic name.
constexpr ContextKey sTypeId
Numeric identifier of the single type/algorithm involved (NOT a DataEncoding see encoding).
constexpr ContextKey sTypeName
Symbolic name of the single type/algorithm involved (NOT a DataEncoding see encoding).
constexpr ContextKey sEncoding
DataEncoding name in play, and ONLY that (e.g.
constexpr ContextKey sSizeActual
Observed BYTE/ELEMENT count at the failure site, decimal.
constexpr ContextKey sSizeBlock
Cipher/encoding block size in BYTES, decimal.
constexpr ContextKey sSizeExpected
BYTE/ELEMENT count the operation required, decimal.
constexpr ContextKey sSizeMax
Maximum permitted BYTE/ELEMENT count, decimal.
constexpr ContextKey sSizeMin
Minimum permitted BYTE/ELEMENT count, decimal.
constexpr ContextKey sLength
A count that is NEITHER bounded NOR compared, decimal.
constexpr ContextKey sExpected
Generic expected value for a NON-size equality/match constraint.
constexpr ContextKey sActual
Generic received-side value of a NON-size compare (the sole received-side key; there is no got/received).
constexpr ContextKey sLimit
Configured ceiling that was exceeded (timeout, quota), NON-size, decimal.
constexpr ContextKey sMin
Minimum bound of a permitted NON-size scalar range.
constexpr ContextKey sMax
Maximum bound of a permitted NON-size scalar range.
constexpr ContextKey sCountActual
Observed count when reporting a count comparison, decimal.
constexpr ContextKey sCountExpected
Expected count when reporting a count comparison, decimal.
constexpr ContextKey sCountTotal
Total count of a population relevant to the error an unbounded, uncompared count (e.g.
constexpr ContextKey sIndex
Generic zero/one-based positional index at the failure site (a position, not a size), decimal.
constexpr ContextKey sOperationIndex
Index of the failing element within a batch/array request (a position, not a size), decimal.
constexpr ContextKey sOffset
Byte offset within a buffer/stream (a position, not a size), decimal.
constexpr ContextKey sValue
A data value or input fragment involved at the failure site (NOT a compare side for those use actual/expected).
constexpr ContextKey sFieldName
Name of the field/member/component/named item involved (struct field, date component, etc.), verbatim.
constexpr ContextKey sUri
Generic URI fact (security policy URI, etc.) not covered by a more specific key, verbatim.
constexpr ContextKey sApplicationUri
ApplicationUri asserted by a peer or certificate, verbatim.
constexpr ContextKey sEndpointAddress
Resolved host/address of an endpoint, verbatim.
constexpr ContextKey sEndpointName
Configured endpoint name referenced, verbatim.
constexpr ContextKey sEndpointPolicyId
The endpoint's selected user-token policy id, verbatim.
constexpr ContextKey sEndpointPort
TCP port of an endpoint, decimal.
constexpr ContextKey sEndpointUrl
Full endpoint URL, verbatim (also used for a connection target URL).
constexpr ContextKey sRemoteAddress
Peer's remote network address on a connection, verbatim.
constexpr ContextKey sSecurityMode
MessageSecurityMode in effect or required, rendered SYMBOLICALLY via ua::to_string(MessageSecurityMode) (e.g.
constexpr ContextKey sSecurityModeValue
OPTIONAL numeric companion to security.mode, used only where the raw integer is itself the fact (e.g.
constexpr ContextKey sSecurityPolicy
Security policy in effect or required, as its URI (there is no public symbolic SecurityPolicy name to render).
constexpr ContextKey sSecurityTokenActiveId
Currently-active SecurityToken id during a token mismatch, decimal.
constexpr ContextKey sSecurityTokenId
SecurityToken id referenced by the message, decimal.
constexpr ContextKey sSecurityTokenPendingId
Pending/renewing SecurityToken id during a token mismatch, decimal.
constexpr ContextKey sTokenKind
User identity token kind presented, as the symbolic UserTokenType enum name.
constexpr ContextKey sTokenPolicyId
UserTokenPolicy id referenced, verbatim.
constexpr ContextKey sCertificateFamilyActual
Certificate/key family actually presented by the token, symbolic.
constexpr ContextKey sCertificateFamilyExpected
Certificate/key family the channel or policy required, symbolic.
constexpr ContextKey sCertificateNotAfter
NotAfter validity bound of the certificate.
constexpr ContextKey sCertificateNotBefore
NotBefore validity bound of the certificate.
constexpr ContextKey sCertificateSerialNumber
Serial number of the certificate involved.
constexpr ContextKey sCertificateSubject
Subject (e.g. CN) of the certificate involved, verbatim.
constexpr ContextKey sCertificateThumbprint
Thumbprint of the certificate involved, as lowercase space-separated hex octets.
constexpr ContextKey sChainDepth
Depth in the certificate chain where validation failed (a position, not a size), decimal.
constexpr ContextKey sOmittedDepth
Number of inner DiagnosticInfo / ErrorDetail chain levels omitted by the client-side depth cap (a count, decimal).
constexpr ContextKey sCryptoCiphertextSize
Ciphertext buffer size in BYTES, decimal.
constexpr ContextKey sCryptoCurve
Elliptic-curve group name involved (the queryable EC fact).
constexpr ContextKey sCryptoCurveDegree
Bit degree of the elliptic curve.
constexpr ContextKey sCryptoDataSize
Generic crypto input data size in BYTES, decimal.
constexpr ContextKey sCryptoError
OpenSSL error-queue string (a library diagnostic, not an SDK StatusCode).
constexpr ContextKey sCryptoInfoSize
HKDF info/context size in BYTES, decimal.
constexpr ContextKey sCryptoIvExpected
IV length in BYTES the cipher required, decimal (pairs with crypto_iv_size).
constexpr ContextKey sCryptoIvSize
Initialization-vector size in BYTES, decimal.
constexpr ContextKey sCryptoKeySize
Key length in BYTES (unit always bytes), decimal.
constexpr ContextKey sCryptoKeySizeExpected
Key length in BYTES the cipher/operation required (unit always bytes), decimal (pairs with crypto_key_size).
constexpr ContextKey sCryptoNid
OpenSSL numeric object identifier (NID) involved.
constexpr ContextKey sCryptoPlaintextSize
Plaintext buffer size in BYTES, decimal.
constexpr ContextKey sCryptoPrivatekeyPresent
Whether a private key was available for the operation (boolean rendered "true"/ "false").
constexpr ContextKey sCryptoPrivatekeySize
Private-key blob size in BYTES, decimal.
constexpr ContextKey sCryptoPublickeySize
Public-key blob size in BYTES, decimal.
constexpr ContextKey sCryptoRandStatus
RAND_status() result from the crypto RNG (the raw OpenSSL return), decimal.
constexpr ContextKey sCryptoSaltSize
KDF salt size in BYTES, decimal.
constexpr ContextKey sCryptoSecretSize
Shared-secret size in BYTES, decimal.
constexpr ContextKey sCryptoSeedSize
KDF seed size in BYTES, decimal.
constexpr ContextKey sCryptoSignatureSize
Signature size in BYTES, decimal.
constexpr ContextKey sSequenceLastSeen
Last received sequence number when a sequencing error occurred, decimal.
constexpr ContextKey sRequestHandle
RequestHeader.requestHandle the client-supplied handle echoed in the Response, decimal.
constexpr ContextKey sRequestId
Transport/secure-channel request id (channel-assigned, per-chunk), decimal.
constexpr ContextKey sChannelId
SecureChannel id correlating the failure, decimal.
constexpr ContextKey sSecureChannelExpired
Whether the SecureChannel had expired at the failure site (boolean rendered "true"/ "false").
constexpr ContextKey sStateChannel
Channel state-machine value at the failure site.
constexpr ContextKey sServerIndex
ServerIndex referenced in an ExpandedNodeId/server table, decimal.
constexpr ContextKey sServerTimestamp
Server timestamp fact relevant to the failure.
constexpr ContextKey sSessionId
Session id (a NodeId) correlating the failure, rendered via ua::to_string(NodeId).
constexpr ContextKey sSubscriptionId
Subscription id correlating the failure, decimal.
constexpr ContextKey sMonitoredItemId
MonitoredItem id/handle correlating the failure, decimal.
constexpr ContextKey sEventId
EventId the operation names, base64 via ua::to_string(ByteString).
constexpr ContextKey sListenerHandle
Server listener handle referenced, decimal.
constexpr ContextKey sListenerName
Configured listener name referenced, verbatim.
constexpr ContextKey sReverseConnectHandle
Reverse-connect handle referenced, decimal.
constexpr ContextKey sFileErrorCode
OS/library file error code (NOT an SDK StatusCode), decimal.
constexpr ContextKey sFilePath
Filesystem path involved, verbatim.
constexpr ContextKey sDirectory
Directory path involved, verbatim.
constexpr ContextKey sLocale
Locale id relevant to the failure, verbatim.
constexpr ContextKey sMethod
Method/operation name at the failure site, verbatim.
constexpr ContextKey sService
OPC UA service name at the failure site, verbatim.
constexpr ContextKey sBitClientValue
Client-supplied OptionSet bit value during a merge mismatch, as fixed-width lowercase hex (e.g.
constexpr ContextKey sBitIndex
Bit position involved in an OptionSet/encoding error (a position), decimal.
constexpr ContextKey sBitName
Symbolic name of the bit involved, verbatim.
constexpr ContextKey sBitServerMask
Server-side valid OptionSet bit mask during a merge mismatch, as fixed-width lowercase hex (e.g.
constexpr ContextKey sSourceLocation
file:line location within an INPUT DOCUMENT (NodeSet/XML), verbatim NOT the SDK component source location (that is carried separately on ErrorDetail).
constexpr ContextKey sPullFailedState
Symbolic FSM state the pull-cert cycle failed in (e.g. "RequestingCert"), verbatim.
constexpr ContextKey sPullFailureCount
Consecutive-failure count at the failing pull-cert cycle (INCLUDING this failure), decimal.
constexpr ContextKey sPullGroupId
Certificate-group NodeId being serviced when the pull-cert cycle failed, via ua::to_string(NodeId).
constexpr ContextKey sPullGdsRequestId
GDS-issued certificate-request id in flight when the pull-cert cycle failed, as hex octets.
constexpr ContextKey sErrorMessage
Free-form diagnostic message from a lower layer or a caught exception (e.what() / transport errorDescription / a pre-formatted reason), verbatim.
ua::UaException
class
The exception thrown by the SDK's throwing (*_sync) API surface.
Carries the full StatusCode that caused the failure, including any attached ErrorDetail and the source location of the throw site. The throwing *_sync convenience wrappers raise this on failure; the callback-canonical async and try_sync variants never throw and instead surface failures through Result.
Functions
UaException(StatusCode status, source_location location=BOOST_CURRENT_LOCATION)
Constructs from a rich StatusCode that may carry an ErrorDetail.
status(StatusCode) - The failing StatusCode, including any attached detail.location(source_location) - The throw site; defaults to the caller's location.
UaException(Status status, std::shared_ptr< const ErrorDetail > detail, source_location location=BOOST_CURRENT_LOCATION)
Constructs from a bare Status paired with a separately held detail.
status(Status) - The symbolic failure code.detail(std::shared_ptr< const ErrorDetail >) - The associated ErrorDetail; may be null.location(source_location) - The throw site; defaults to the caller's location.
~UaException() override
UaException(UaException &&other) noexcept
Move-constructs from other, transferring its status, detail, location, and message.
other(UaException &&) - Exception to move from; left in a valid but unspecified state.
UaException & operator=(UaException &&other) noexcept
Move-assigns from other, transferring its status, detail, location, and message.
other(UaException &&) - Exception to move from; left in a valid but unspecified state.
Returns: *this.
UaException(const UaException &)=default
Copy-constructs an independent exception; the ErrorDetail is shared, not cloned.
UaException & operator=(const UaException &)=default
Copy-assigns; the ErrorDetail is shared, not cloned.
Returns: *this.
Status status() const
Returns the bare symbolic Status, masked to the high 16 bits.
Returns: The high-16-bit symbolic code.
StatusCode status_code() const noexcept
Returns the full 32-bit StatusCode, including any attached ErrorDetail.
Returns: The complete StatusCode.
const ErrorDetail * detail() const noexcept
Returns a non-owning pointer to the attached ErrorDetail.
Returns: The detail, or nullptr if none is attached. Valid only while this exception is alive.
std::shared_ptr< const ErrorDetail > take_detail() const noexcept
Returns the shared ErrorDetail for handoff into a Result.
Returns: The shared detail, or an empty pointer if none is attached.
const char * what() const noexcept override
Returns the human-readable message for this exception.
Returns: A null-terminated message owned by this exception.
ua::ExecutionLimits
struct
Configured maxima that bound the work a single request may perform.
These are the configured ceilings (not per-call progress state): they seed the initial values of the path-local execution budget tokens (StackDepth, DepthBudget, LoopLimit) at request entry points. Exceeding a seeded budget during processing fails the operation with ua::Status::BadEncodingLimitsExceeded rather than risking unbounded stack growth or non-terminating traversal of the address space.
Every limit must be strictly greater than zero; a configuration carrying a zero limit is rejected at validation time.
StackDepth, DepthBudget, LoopLimit, ExecutionLimits::mDecodeWorkLimit, ExecutionLimits::mDecodeRecursionDepthLimit, ExecutionLimits::mInstantiationDepthLimit, ExecutionLimits::mLoopLimit
Functions
bool operator==(const ExecutionLimits &) const =default
Compares two limit sets field-by-field for equality.
Returns: true when every corresponding limit is equal; false otherwise.
Public attributes
size_t mDecodeWorkLimit
Maximum cumulative node/edge WORK a single NodeSet traversal may perform, in work units.
size_t mDecodeRecursionDepthLimit
Maximum LIVE recursion / nesting depth a single encode/decode may reach, in recursion levels.
size_t mInstantiationDepthLimit
Maximum logical descent a single instantiation traversal may reach, in descent levels.
size_t mLoopLimit
Maximum number of loop iterations permitted for a single request, in iterations.
Static attributes
constexpr size_t sMinWorkableLoopLimit
Smallest mLoopLimit the server's own NS0 NodeSet import can complete under.
ua::LogField
struct
A single structured key/value pair attached to a log entry.
Both members are non-owning views into caller-owned storage; a LogField does not extend the lifetime of the data it references and must not outlive it.
Public attributes
std::string_view key
Non-owning field name; storage is owned by the caller.
LogValue value
The field's typed value (see LogValue).
ua::LogEntry
struct
A structured log record handed to a LogSink for emission.
The view members (category, fields) and any string in fields reference caller-owned storage that need only remain valid for the duration of the LogSink::log() call; sinks that retain data beyond that call must copy it. message is owned by the entry itself.
LogSink, LogField, LogLevel
Public attributes
LogLevel level
Severity of the record.
std::string_view category
Non-owning logical source/category name; caller-owned storage.
std::string message
The fully formatted, owned message text.
std::span< const LogField > fields
Non-owning view of the structured fields; caller-owned.
ua::LogSink
class
A destination that emits structured log entries.
Implementations forward each LogEntry to a backend (console, file, syslog, test buffer, ...). The logging facade may invoke log() concurrently from any thread, so implementations must be thread-safe.
LogEntry, LogLevel
Functions
LogSink()=default
~LogSink()=default
void log(const LogEntry &entry)=0
Emits a single structured log entry.
entry(const LogEntry &) - The record to emit; valid only for the duration of the call.
ua::ConsoleLogSink
class
A LogSink that writes each entry as a single formatted text line to standard error.
Each entry is rendered as <timestamp> [<level>] [<category>] <key>=<value> ... <message>, where the timestamp is the local wall-clock time at which the entry is processed. String field values containing spaces are quoted so they cannot bleed into adjacent fields. The formatted line is written to stderr.
Stateless and thread-safe: instances hold no mutable state and may be shared and invoked concurrently from any thread. LogSink
Functions
void log(const LogEntry &entry) override
Writes entry as one formatted line to stderr.
entry(const LogEntry &) - Log entry to render; referenced only for the duration of the call.
ua::FileLogSink
class
A LogSink that writes each entry as a single formatted text line to a file.
Each entry is rendered exactly as ConsoleLogSink renders it - <timestamp> [<level>] [<category>] <key>=<value> ... <message> - using the same shared formatter, so file and console output are byte-for-byte identical. String field values containing a space are quoted so they cannot bleed into adjacent fields. Each line is flushed immediately so a crash cannot lose the most recently written entries.
Stateful and thread-safe: the sink owns the underlying std::ofstream and serializes every log() write with an internal mutex, so it may be shared and invoked concurrently from any thread. Because it owns a file stream and a mutex it is neither copyable nor movable.
Error handlingThe constructor opens the target file and throws UaException (carrying an ErrorDetail with the file path) if the file cannot be opened. A successfully constructed instance is therefore guaranteed to have an open file; the open failure is never silently swallowed. ConsoleLogSink, LogSink
Functions
FileLogSink(std::string_view path, bool append=true)
Opens path and creates a sink that appends or truncates per append.
path(std::string_view) - Filesystem path of the log file to write. Parent directories must already exist; the file itself is created if missing.append(bool) - When true (the default) new entries are appended to any existing content; when false the file is truncated on open.
~FileLogSink() override=default
Flushes and closes the underlying file.
void log(const LogEntry &entry) override
Writes entry as one formatted line to the file and flushes it.
entry(const LogEntry &) - Log entry to render; referenced only for the duration of the call.
ua::Logger
class
A category-scoped, level-filtered handle for emitting log entries.
A Logger holds a shared LogSink, a shared atomic minimum LogLevel, and a category string. The per-level methods (trace, debug, info, warning, error, critical) format their message with fmt and forward it to the sink only when the level passes the is_enabled filter, so a disabled level costs no formatting. A default-constructed Logger has no sink and is a silent no-op for every call.
Copying a Logger shares the underlying sink and level; the level is read atomically, so an instance may be used from multiple threads concurrently. The sink is responsible for its own thread safety (see LogSink::log).
Functions
Logger()=default
Constructs a null logger whose every logging call is a no-op.
Constructs a logger bound to a sink, a shared level filter, and a category.
sink(std::shared_ptr< LogSink >) - Destination for emitted entries; shared ownership is retained. If null, the logger behaves as a no-op.level(std::shared_ptr< std::atomic< LogLevel > >) - Shared atomic minimum level; entries below it are dropped. Mutating it through the shared pointer reconfigures every Logger sharing it. Must be non-null when sink is non-null.category(std::string) - Category tag attached to every entry this logger emits.
bool is_enabled(LogLevel level) const noexcept
Reports whether an entry at level would be emitted.
level(LogLevel) - Level to test.
Returns: true if a sink is bound and level is at or above the current minimum level; false otherwise.
void trace(fmt::format_string< Args... > fmt, Args &&... args) const
Emits a Trace-level entry, formatting the message only if Trace is enabled.
fmt(fmt::format_string< Args... >) - Compile-checked fmt format string.args(Args &&...) - Format arguments; wrap costly values in log_lazy to defer their formatting.
void debug(fmt::format_string< Args... > fmt, Args &&... args) const
Emits a Debug-level entry, formatting the message only if Debug is enabled.
fmt(fmt::format_string< Args... >) - Compile-checked fmt format string.args(Args &&...) - Format arguments; wrap costly values in log_lazy to defer their formatting.
void info(fmt::format_string< Args... > fmt, Args &&... args) const
Emits an Info-level entry, formatting the message only if Info is enabled.
fmt(fmt::format_string< Args... >) - Compile-checked fmt format string.args(Args &&...) - Format arguments; wrap costly values in log_lazy to defer their formatting.
void warning(fmt::format_string< Args... > fmt, Args &&... args) const
Emits a Warning-level entry, formatting the message only if Warning is enabled.
fmt(fmt::format_string< Args... >) - Compile-checked fmt format string.args(Args &&...) - Format arguments; wrap costly values in log_lazy to defer their formatting.
void error(fmt::format_string< Args... > fmt, Args &&... args) const
Emits an Error-level entry, formatting the message only if Error is enabled.
fmt(fmt::format_string< Args... >) - Compile-checked fmt format string.args(Args &&...) - Format arguments; wrap costly values in log_lazy to defer their formatting.
void critical(fmt::format_string< Args... > fmt, Args &&... args) const
Emits a Critical-level entry, formatting the message only if Critical is enabled.
fmt(fmt::format_string< Args... >) - Compile-checked fmt format string.args(Args &&...) - Format arguments; wrap costly values in log_lazy to defer their formatting.
void trace(std::initializer_list< LogField > fields, fmt::format_string< Args... > fmt, Args &&... args) const
Emits a Trace-level entry with structured fields, formatting only if Trace is enabled.
fields(std::initializer_list< LogField >) - Key/value pairs attached to the entry for structured sinks. The referenced LogField data must outlive the call.fmt(fmt::format_string< Args... >) - Compile-checked fmt format string.args(Args &&...) - Format arguments; wrap costly values in log_lazy to defer their formatting.
void debug(std::initializer_list< LogField > fields, fmt::format_string< Args... > fmt, Args &&... args) const
Emits a Debug-level entry with structured fields, formatting only if Debug is enabled.
fields(std::initializer_list< LogField >) - Key/value pairs attached to the entry for structured sinks. The referenced LogField data must outlive the call.fmt(fmt::format_string< Args... >) - Compile-checked fmt format string.args(Args &&...) - Format arguments; wrap costly values in log_lazy to defer their formatting.
void info(std::initializer_list< LogField > fields, fmt::format_string< Args... > fmt, Args &&... args) const
Emits an Info-level entry with structured fields, formatting only if Info is enabled.
fields(std::initializer_list< LogField >) - Key/value pairs attached to the entry for structured sinks. The referenced LogField data must outlive the call.fmt(fmt::format_string< Args... >) - Compile-checked fmt format string.args(Args &&...) - Format arguments; wrap costly values in log_lazy to defer their formatting.
void warning(std::initializer_list< LogField > fields, fmt::format_string< Args... > fmt, Args &&... args) const
Emits a Warning-level entry with structured fields, formatting only if Warning is enabled.
fields(std::initializer_list< LogField >) - Key/value pairs attached to the entry for structured sinks. The referenced LogField data must outlive the call.fmt(fmt::format_string< Args... >) - Compile-checked fmt format string.args(Args &&...) - Format arguments; wrap costly values in log_lazy to defer their formatting.
void error(std::initializer_list< LogField > fields, fmt::format_string< Args... > fmt, Args &&... args) const
Emits an Error-level entry with structured fields, formatting only if Error is enabled.
fields(std::initializer_list< LogField >) - Key/value pairs attached to the entry for structured sinks. The referenced LogField data must outlive the call.fmt(fmt::format_string< Args... >) - Compile-checked fmt format string.args(Args &&...) - Format arguments; wrap costly values in log_lazy to defer their formatting.
void critical(std::initializer_list< LogField > fields, fmt::format_string< Args... > fmt, Args &&... args) const
Emits a Critical-level entry with structured fields, formatting only if Critical is enabled.
fields(std::initializer_list< LogField >) - Key/value pairs attached to the entry for structured sinks. The referenced LogField data must outlive the call.fmt(fmt::format_string< Args... >) - Compile-checked fmt format string.args(Args &&...) - Format arguments; wrap costly values in log_lazy to defer their formatting.
Logger with_category(std::string category) const
Returns a copy of this logger that tags entries with a different category.
category(std::string) - New category string for the returned logger.
Returns: A logger sharing this one's sink and level filter but using category.
ua::Random
class
A uniform random integer generator over a closed range.
Each instance owns its own seeded engine and distribution; draws are produced by invoking the call operator. The generator is seeded from std::random_device on construction and is therefore suitable for non-cryptographic uses such as request handles and nonce-style identifiers.
Not thread-safe: a single instance must not be invoked concurrently from multiple threads. Use a separate instance per thread, or serialise access externally.
T Integer type produced by the generator; must be a type supported by std::uniform_int_distribution.
Functions
Random()
Constructs a generator spanning the full non-negative range of T.
Random(T min, T max)
Constructs a generator spanning the closed range [min, max].
min(T) - Smallest value the generator may produce, inclusive.max(T) - Largest value the generator may produce, inclusive.
T operator()()
Draws the next uniformly distributed value from the configured range.
Returns: A value in the closed range fixed at construction.
ua::Resolver
class
Asynchronously resolves a hostname and port to a list of TCP endpoints.
Wraps an Asio TCP resolver with a configurable timeout. Instances are heap-managed and must be created via create so that shared_from_this is valid; the resolver keeps itself alive for the duration of an in-flight resolution by capturing a weak reference in its handlers.
A single resolver serves one resolution at a time: while a resolve is in flight, a further call to resolve_endpoints_async fails with ua::Status::BadInvalidState. The completion callback runs on a worker thread of the executor passed to create - do not block it.
Member types
std::function< void(EndpointListResult)> CompleteCallback
Callback type that receives the resolution outcome.
Static functions
shared_ptr< Resolver > create(boost::asio::any_io_executor executor, optional< std::chrono::seconds > timeout)
Creates a heap-managed resolver bound to executor.
executor(boost::asio::any_io_executor) - Executor on which resolutions run and on whose worker threads completion callbacks are invoked.timeout(optional< std::chrono::seconds >) - Default resolution timeout, in seconds, applied when a per-call timeout is not given; nullopt selects a built-in default of 5 seconds.
Returns: A shared owner of the new resolver.
Functions
void resolve_endpoints_async(string_view hostname, uint16_t port, optional< std::chrono::seconds > timeout, CompleteCallback callback) noexcept
Resolves hostname and port to TCP endpoints, completing asynchronously.
hostname(string_view) - Host to resolve. May be a DNS name or a literal IP address.port(uint16_t) - TCP port number combined with each resolved address.timeout(optional< std::chrono::seconds >) - Maximum time to wait, in seconds; nullopt uses the default supplied to create.callback(CompleteCallback) - Receives the outcome: on success the Result holds the EndpointList; on failure it carries an ErrorDetail (for example ua::Status::BadInvalidState if a resolution is already in progress, ua::Status::BadTimeout on timeout, or ua::Status::BadTcpInternalError on resolver error). Never throws.
EndpointListResult try_resolve_endpoints_sync(string_view hostname, uint16_t port, optional< std::chrono::seconds > timeout) noexcept
Resolves hostname and port to TCP endpoints, blocking until complete.
hostname(string_view) - Host to resolve. May be a DNS name or a literal IP address.port(uint16_t) - TCP port number combined with each resolved address.timeout(optional< std::chrono::seconds >) - Maximum time to wait, in seconds; nullopt uses the default supplied to create.
Returns: The resolved EndpointList, or an ErrorDetail on failure. Never throws.
EndpointList resolve_endpoints_sync(string_view hostname, uint16_t port, optional< std::chrono::seconds > timeout)
Resolves hostname and port to TCP endpoints, blocking until complete.
hostname(string_view) - Host to resolve. May be a DNS name or a literal IP address.port(uint16_t) - TCP port number combined with each resolved address.timeout(optional< std::chrono::seconds >) - Maximum time to wait, in seconds; nullopt uses the default supplied to create.
Returns: The resolved EndpointList.
ua::WorkBudget
class
A node/edge work budget that bounds the cost of a graph traversal or decode.
Counts units of work as they are performed and throws once either bound is crossed, protecting against maliciously crafted inputs (e.g. deeply nested or densely linked structures) that would otherwise exhaust resources. Budget state lives in the instance; copies are independent.
Not thread-safe: a single budget must be confined to one thread for the duration of a traversal.
StackDepth, LoopLimit
Functions
WorkBudget(size_t maxNodes, size_t maxEdges)
Constructs a budget bounded to maxNodes node units and maxEdges edge units.
maxNodes(size_t) - Maximum number of node units that may be consumed (inclusive).maxEdges(size_t) - Maximum number of edge units that may be consumed (inclusive).
void consume_node()
Charges one node unit against the budget.
void consume_edge()
Charges one edge unit against the budget.
size_t nodes_used() const
Returns the number of node units consumed so far.
Returns: The number of node units charged against this budget so far.
size_t edges_used() const
Returns the number of edge units consumed so far.
Returns: The number of edge units charged against this budget so far.
ua::StackDepth
class
A shared work-budget passed through codecs and generated decode paths.
Carries TWO independent guards against decoding bombs, both throwing Status::BadEncodingLimitsExceeded when crossed: a cumulative nodes+edges WORK budget (fan-out / total-cost protection). The edge bound defaults to the square of the node bound (saturating at SIZE_MAX) so a limit of N can traverse the denser edge sets that explicit accounting exposes. a live recursion-DEPTH counter (call-stack protection). enter_recursion increments it and the returned RAII scope decrements it on unwind, so it tracks the CURRENT structural nesting depth - bounding deep-narrow recursion (a native stack-overflow DoS) WITHOUT penalising wide-shallow structures (the depth unwinds after each sibling). Capped at the same configured limit, un-squared.
Budget state is reference-counted: all copies of a StackDepth share one budget, so charges made through any copy are seen by the others. Not thread-safe; confine a budget (and its copies) to a single traversal on one thread.
WorkBudget, LoopLimit
Functions
StackDepth(size_t maxWork, size_t maxDepth=sDefaultMaxDepth)
Constructs a budget bounded to maxWork node units (edge bound derived as maxWork^2, saturating at SIZE_MAX) and maxDepth live recursion units.
maxWork(size_t) - Maximum cumulative node units (inclusive); the edge bound is maxWork^2.maxDepth(size_t) - Maximum LIVE structural recursion depth (inclusive) - bounds deep-narrow nesting against native stack overflow; decremented as the recursion unwinds.
StackDepth(const StackDepth &)=default
Copies a reference to the shared budget; the copy charges against the same state.
StackDepth(StackDepth &&) noexcept=default
Moves the reference to the shared budget.
StackDepth & operator=(const StackDepth &)=default
Rebinds this handle to another shared budget; the copy charges against the same state.
Returns: Reference to this budget handle.
StackDepth & operator=(StackDepth &&) noexcept=default
Moves the reference to the shared budget.
Returns: Reference to this budget handle.
~StackDepth()=default
Destroys this handle, releasing its reference to the shared budget.
void consume_node()
Charges one node unit against the shared budget.
void consume_edge()
Charges one edge unit against the shared budget.
DepthScope enter_recursion()
Enters one structural recursion level: charges the live depth counter and returns an RAII scope that releases it on destruction (so the counter tracks CURRENT nesting depth and unwinds as the recursion returns - bounding deep-narrow nesting without penalising width).
Returns: An RAII DepthScope owning the charged depth unit; it releases the unit (decrementing the live-depth counter) when destroyed as the recursion unwinds.
Static attributes
constexpr size_t sDefaultMaxDepth
Default recursion-depth cap (native-stack-overflow guard for hostile, deeply-nested wire input).
ua::LoopLimit
class
An iteration counter that bounds the number of passes through a loop.
Guards unbounded loops driven by untrusted input by capping total iterations. Choose the throwing consume_iteration or the non-throwing try_increment depending on whether the call site treats budget exhaustion as an error or as a normal stop condition.
Not thread-safe; confine an instance to a single loop on one thread.
WorkBudget, StackDepth
Functions
LoopLimit(size_t maxDepth)
Constructs a limit allowing at most maxDepth iterations.
maxDepth(size_t) - Maximum number of iterations permitted (inclusive).
void consume_iteration()
Charges one iteration against the limit.
bool try_increment()
Charges one iteration and reports whether the limit still holds, without throwing.
Returns: true if the iteration was within the bound; false once the bound is exceeded.
bool increment_and_test()
Alias of try_increment that charges one iteration and reports whether the limit holds.
Returns: true if the iteration was within the bound; false once the bound is exceeded.
ua::DepthBudget
struct
A per-call recursion-depth budget consumed monotonically as an async traversal descends.
Unlike StackDepth::enter_recursion (a live RAII counter that unwinds with the native stack in the synchronous codec), this token is a path-local progress counter for callback/continuation flows where there is no native stack to unwind: it is passed by value down a call path and decremented locally via consume(), so it bounds the CUMULATIVE logical descent of one branch. Configured maxima live in ExecutionLimits and seed the initial value at an entry point. Copies are independent, so each branch of a traversal carries its own remaining count.
StackDepth, LoopLimit, ExecutionLimits
Functions
void consume(size_t n=1)
Charges n levels against the remaining depth budget.
n(size_t) - Number of depth levels to consume; defaults to one.
Public attributes
size_t mRemaining
Recursion levels still available before the budget is exhausted.
ua::Result
class
A value-or-error type holding either a T (good) or a StatusCode (error).
The non-throwing return surface for OPC UA operations: a good result owns a value of type T, an error result owns a StatusCode whose code is Bad or Uncertain. Any ErrorDetail travels inside that StatusCode - Result has no separate detail field, so propagating a Result preserves the detail without extra plumbing.
A value is convertible to a good result and a StatusCode (or Status, via its implicit conversion) to an error result, so the type is the natural callback payload for the async API variant and the natural return of the try_sync variant.
T Held value type for a good result. See Result<void> for the no-value case and Result<StatusCode> for the StatusCode-valued case.
Functions
Result(T value)
Constructs a good result holding value.
value(T) - The held value; moved in.
Result(StatusCode error) noexcept
Constructs an error result from a (possibly rich) StatusCode.
error(StatusCode) - The error status; must not be Good.
Result(StatusCode error, shared_ptr< const ErrorDetail > detail) noexcept
Constructs an error result from a StatusCode and a shared ErrorDetail.
error(StatusCode) - The error status; must not be Good.detail(shared_ptr< const ErrorDetail >) - Error detail to attach; shared, not copied. May be null.
Copy-constructs an independent result; any ErrorDetail is shared, not cloned.
Move-constructs from another result, leaving it in a valid but unspecified state.
Copy-assigns; any ErrorDetail is shared, not cloned.
Returns: A reference to this result.
Move-assigns, leaving the source in a valid but unspecified state.
Returns: A reference to this result.
~Result()=default
Destroys the result, releasing the held value and any error detail.
bool is_good() const noexcept
Returns true if this holds a value (status is Good).
Returns: true if the status is Good.
bool is_bad() const noexcept
Returns true if the status is Bad.
Returns: true if the status is Bad.
bool is_uncertain() const noexcept
Returns true if the status is Uncertain.
Returns: true if the status is Uncertain.
operator bool() const noexcept
Returns true if this holds a value; equivalent to is_good().
Returns: true if the result is good; equivalent to is_good().
StatusCode status_code() const noexcept
Returns the status code: Good when holding a value, the error code otherwise.
Returns: The status code: Good when good, otherwise the error code.
const ErrorDetail * error_detail() const noexcept
Returns the attached error detail, or null if none.
Returns: The attached error detail, or null if none.
const shared_ptr< const ErrorDetail > & shared_detail() const noexcept
Returns the attached error detail as a shared pointer (null if none).
Returns: The attached error detail as a shared pointer, or null if none.
const T & value() const &
Returns a reference to the held value.
Returns: The held value.
T & value() &
Returns a mutable reference to the held value.
Returns: The held value.
T && value() &&
Moves the held value out of this Result.
Returns: The held value, moved.
T value_or(const T &fallback) const &
Returns the held value if good, otherwise fallback.
fallback(const T &) - Value returned on an error result.
Returns: The held value if good, otherwise fallback.
T value_or(T fallback) &&
Returns the held value (moved) if good, otherwise fallback.
fallback(T) - Value returned on an error result.
Returns: The held value (moved) if good, otherwise fallback.
auto transform(F &&f) const &-> Result< std::invoke_result_t< F, const T & > >
Maps the held value through f, propagating an error unchanged.
f(F &&) - Transformation applied to the held value.
Returns: Result<U> where U is the return type of f.
auto transform(F &&f) &&-> Result< std::invoke_result_t< F, T && > >
Maps the held value through f, propagating an error unchanged (rvalue overload).
f(F &&) - Transformation applied to the moved held value.
Returns: Result<U> where U is the return type of f.
auto and_then(F &&f) const &-> std::invoke_result_t< F, const T & >
Chains a Result-returning operation onto the held value (monadic bind).
f(F &&) - Operation applied to the held value.
Returns: The Result<U> produced by f, or this result's error forwarded.
auto and_then(F &&f) &&-> std::invoke_result_t< F, T && >
Chains a Result-returning operation onto the held value (rvalue overload).
f(F &&) - Operation applied to the moved held value.
Returns: The Result<U> produced by f, or this result's error forwarded.
Result transform_error(F &&f) const &
Maps the error through f, propagating a good value unchanged.
f(F &&) - Mapping applied to the error status.
Returns: This result on success, otherwise a Result built from f's output.
Result transform_error(F &&f) &&
Maps the error through f, propagating a good value unchanged (rvalue overload).
f(F &&) - Mapping applied to the error status.
Returns: This result on success, otherwise a Result built from f's output.
ua::BatchResult
struct
Outcome of a batch operation: a batch-level status plus per-item results.
A batch carries two distinct layers of status. The batch-level batchStatus reports whether the request as a whole was accepted and processed; the per-item items report the individual outcomes once it was. The two are independent - a good batch may still contain bad items.
When batchStatus.is_good() the batch itself was accepted and items holds the per-item results, each of which may independently be good or bad.
When batchStatus.is_bad() the batch failed as a whole (e.g. authorization denied, malformed request, pre-flight service failure). items may be empty, and any ErrorDetail attached to batchStatus describes the batch-level cause.
T Per-item result type stored in items. Result, VoidResult
Public attributes
VoidResult batchStatus
Batch-level outcome: good if the request as a whole was accepted.
std::vector< T > items
Per-item results, in request order.
ua::utils::Timer
class
A lightweight stopwatch for ad-hoc elapsed-time measurement.
Measures a single interval against std::chrono::steady_clock: start records the origin and stop prints the elapsed duration with a caller-supplied label. Intended for hand profiling, not production timing. Not thread-safe; a single instance must not be driven concurrently.
Functions
void start()
Records the current steady-clock time as the start of the measured interval.
void stop(string_view message)
Prints the time elapsed since the most recent start to standard output.
message(string_view) - Label identifying the measured interval in the output.
Enumerations
ua::TransportProfileId
enum
Identifier of an OPC UA transport profile.
UaTcpUaScUaBinary- UA-TCP transport with UA-SecureConversation and UA Binary encoding.
ua::LogLevel
enum
Severity of a log record, ordered from most to least verbose.
Trace- Finest-grained diagnostic detail; high-volume tracing.Debug- Diagnostic information useful while developing or debugging.Info- Normal operational events worth recording.Warning- An unexpected condition that did not prevent operation.Error- A failure that aborted the current operation.Critical- A severe failure threatening continued operation.