open62541pp

open62541pp uses the opcua::TypeConverter struct to automatically convert between C++ types and native OPC UA UA_* types.

Automatic Conversions

Many common types are handled automatically. For example, opcua::Variant::assign can accept primitive types directly, but complex types like std::string require explicit conversion or passing the object directly rather than a pointer to avoid compilation errors.

Extending Type Conversion

You can add support for custom types by providing template specializations for opcua::TypeConverter. You must implement fromNative and toNative methods.

namespace opcua {

template <>
struct TypeConverter<std::byte> {
    using NativeType = UA_Byte;
    [[nodiscard]] static std::byte fromNative(const UA_Byte& src) { /* implementation */ }
    [[nodiscard]] static UA_Byte toNative(const std::byte& src) { /* implementation */ }
};

}

namespace opcua {

template <>
struct TypeConverter<std::byte> {
    using NativeType = UA_Byte;
    [[nodiscard]] static std::byte fromNative(const UA_Byte& src) { /* ... */ }
    [[nodiscard]] static UA_Byte toNative(const std::byte& src) { /* ... */ }
};

}

Open62541pp provides two complementary APIs for interacting with the OPC UA address space. Choosing the right one depends on your error handling preference, whether you need batching, and your asynchronous requirements.

The Node API

opcua::Node is an object-oriented handle to a single node identified by an opcua::NodeId. It is designed for concise, sequential code.

• Error Model: Throws opcua::BadStatus exceptions on failure.
• Best for: Writing synchronous scripts, tools, or quick integrations where you are operating on individual nodes one at a time.

The services namespace

Functions in opcua::services mirror the OPC UA service set directly. They are free functions that accept either an opcua::Server or opcua::Client.

• Error Model: Returns opcua::Result<T> and never throws.
• Async Support: Full support via callbacks, futures, deferred execution, or custom completion tokens (asynchronous variants are suffixed with Async).
• Best for: Composing error handling without exceptions, performing batched requests (multiple nodes in one round-trip), and using the full asynchronous model.

// Node API example
opcua::Node node{client, opcua::NodeId{1, 1000}};
node.writeValue(opcua::Variant{42});
auto value = node.readValue().to<int>();

// services namespace example
opcua::Result<opcua::Variant> result = opcua::services::readValue(client, id);
if (result) {
    int v = result->to<int>();
}

Open62541pp uses an asynchronous model adapted from Boost Asio. Asynchronous operations accept a completion token as their final argument. This token determines how the caller receives the result of the operation.

Commonly used tokens include:

• Callback functions: The operation executes a provided function object upon completion.
• opcua::useFuture: Returns a std::future<T> to allow synchronous-style waiting via .get().
• opcua::useDeferred: Returns a callable object that allows you to delay the start of the operation and specify a completion handler later.
• opcua::useDetached: Starts the operation but provides no way to track its result or completion.
• Custom tokens: Users can define their own behavior by specializing the opcua::AsyncResult trait.

Important: Callbacks are executed within the client's or server's event loop. Do not block the event loop inside a callback (e.g., by waiting for other asynchronous results), as this will halt the execution of the entire loop.

// Example of the general pattern for an async operation
template <typename CompletionToken>
auto opcua::services::readAsync(
    opcua::Client& connection,
    const opcua::ReadRequest& request,
    CompletionToken&& token
);

Use opcua::DataTypeBuilder to define brand-new composite types (structures, unions, or enumerations) that have their own OPC UA type identity and binary encoding. This is required when the server exposes a structured type that the client must deserialize.

Struct Layout Requirements

C++ structs used with DataTypeBuilder must have a C-compatible memory layout:

• No virtual functions or inheritance.
• No standard library containers (e.g., std::vector, std::string). For dynamic arrays, use the open62541 convention: a size_t count field immediately followed by a T* pointer field.
• Nullable pointer fields are supported; a nullptr indicates the field is absent.

Registering Types

Describe the binary layout using the builder. The resulting opcua::DataType object must be kept alive for the lifetime of the server or client.

Note on NodeIds: The two NodeId arguments in create* methods are the type's node ID and its binary encoding node ID. These must match the IDs used in the server's address space.

struct Point { float x, y, z; };

const opcua::DataType& getPointDataType() {
    static const opcua::DataType dt = 
        opcua::DataTypeBuilder<Point>::createStructure("Point", {1, 4242}, {1, 1})
            .addField<&Point::x>("x")
            .addField<&Point::y>("y")
            .addField<&Point::z>("z")
            .build();
    return dt;
}