QOpcUaGenericStructHandler Class

Reads a server's data types and decodes/encodes generic structs from/to extension objects. More...

Header:	`#include <QOpcUaGenericStructHandler>`
CMake:	`find_package(Qt6 REQUIRED COMPONENTS OpcUa)` `target_link_libraries(mytarget PRIVATE Qt6::OpcUa)`
qmake:	`QT += opcua`
Since:	Qt 6.7
Inherits:	QObject

List of all members, including inherited members

Public Types

enum class DataTypeKind { Unknown, Struct, Enum, Other }

Public Functions

	QOpcUaGenericStructHandler(QOpcUaClient *client, QObject *parent = nullptr)
bool	addCustomEnumDefinition(const QOpcUaEnumDefinition &definition, const QString &typeId, const QString &name, QOpcUa::IsAbstract isAbstract = QOpcUa::IsAbstract::NotAbstract)
bool	addCustomStructureDefinition(const QOpcUaStructureDefinition &definition, const QString &typeId, const QString &name, QOpcUa::IsAbstract isAbstract = QOpcUa::IsAbstract::NotAbstract)
QOpcUaGenericStructValue	createGenericStructValueForTypeId(const QString &typeId)
QOpcUaGenericStructHandler::DataTypeKind	dataTypeKindForTypeId(const QString &id) const
std::optional<QOpcUaGenericStructValue>	decode(const QOpcUaExtensionObject &extensionObject) const
std::optional<QOpcUaExtensionObject>	encode(const QOpcUaGenericStructValue &value)
QOpcUaEnumDefinition	enumDefinitionForTypeId(const QString &id) const
bool	initialize()
`(since 6.7)` bool	initialized() const
bool	isAbstractTypeId(const QString &id) const
QOpcUaStructureDefinition	structureDefinitionForBinaryEncodingId(const QString &id) const
QOpcUaStructureDefinition	structureDefinitionForTypeId(const QString &id) const
QString	typeIdForBinaryEncodingId(const QString &id) const
QString	typeNameForBinaryEncodingId(const QString &id) const
QString	typeNameForTypeId(const QString &id) const

Signals

void	initializedChanged(bool initialized)

Detailed Description

The binary data encoding used in OPC UA was designed with a small message size in mind and doesn't contain any information about the structure of the data. This means that a decoder must known the structure of the encoded data in advance to be able to decode a data buffer.

Since OPC UA 1.04, nodes of the DataType node class may have the DataTypeDefinition attribute which contain information about the fields of structured types and the mapping of enum values to names. Together with the knowledge about how to decode built-in types, this allows a client to decode generic custom structured types without relying on outside knowledge.

QOpcUaGenericStructHandler traverses the type hierarchy of a server by following the HasSubtype references starting from BaseDataType and reads the DataTypeDefinition attribute of the nodes.

For structured types where a QOpcUaStructureDefinition value is present in the DataTypeDefinition attribute, automatic decoding of extension objects containing them is available. Fields with a built-in type or a type where a C++ data class exists are deserialized to the corresponding Qt OPC UA type, other generic structs are serialized to a nested QOpcUaGenericStructValue. All nested generic struct values must have a QOpcUaStructureDefinition in the server or decoding fails.

The same conditions apply to encoding a custom struct.

Example for decoding a custom struct:

 QOpcUaGenericStructHandler handler(opcuaClient);
 handler.initialize();

 QObject::connect(&handler, &QOpcUaGenericStructHandler::initializedChanged, [opcuaClient, &handler](bool initialized) {
     if (!initialized)
         return;

     auto node = opcuaClient->node("ns=4;i=3003"); // A custom struct test node in the open62541-testserver
     node->readValueAttribute();

     QObject::connect(node, &QOpcUaNode::attributeRead, [node, &handler](QOpcUa::NodeAttributes attr) {
         if (!attr.testFlag(QOpcUa::NodeAttribute::Value) || node->valueAttributeError() != QOpcUa::UaStatusCode::Good)
             return;

         auto extObj = node->valueAttribute().value<QOpcUaExtensionObject>();
         qDebug() << "Got object of type" << handler.typeNameForBinaryEncodingId(extObj.encodingTypeId());

         const auto result = handler.decode(extObj);

         if (!result)
             return;

         qDebug() << *result;
     });
 });

Example for encoding a custom struct:

 QOpcUaGenericStructHandler handler(opcuaClient);
 handler.initialize();

 QObject::connect(&handler, &QOpcUaGenericStructHandler::initializedChanged, [opcuaClient, &handler](bool initialized) {
     if (!initialized)
         return;

     QOpcUaGenericStructValue value = handler.createGenericStructValueForTypeId("ns=4;i=3006");
     value.fieldsRef()["MandatoryMember"] = 23.0;
     value.fieldsRef()["OptionalMember"] = 42.0;

     const auto ext = handler.encode(value);

     if (!ext)
         return;

     // Use the extension object to write a node's value attribute, in a method parameter, etc...
 });

Member Type Documentation

enum class QOpcUaGenericStructHandler::DataTypeKind

This enum type specifies data type kind of a data type node.

Constant	Value	Description
`QOpcUaGenericStructHandler::DataTypeKind::Unknown`	`0`	The type node id is unknown.
`QOpcUaGenericStructHandler::DataTypeKind::Struct`	`1`	The type node id belongs to a structured type.
`QOpcUaGenericStructHandler::DataTypeKind::Enum`	`2`	The type node id belongs to an enum type.
`QOpcUaGenericStructHandler::DataTypeKind::Other`	`3`	The type node id belongs to a type which is not a struct or enum (other built-in types or their subtypes)

Member Function Documentation

`[explicit]` QOpcUaGenericStructHandler::QOpcUaGenericStructHandler(QOpcUaClient **client*, QObject **parent* = nullptr)

Constructs a generic struct handler for client.

bool QOpcUaGenericStructHandler::addCustomEnumDefinition(const QOpcUaEnumDefinition &definition, const QString &typeId, const QString &name, QOpcUa::IsAbstract isAbstract = QOpcUa::IsAbstract::NotAbstract)

Adds the custom enum definition definition to the known types. This can be used to support custom structures the server doesn't expose a StructureDefinition for. The parameters definition, typeId and name are required for proper decoding and encoding. If isAbstract is set, the type can't be encoded and decoded.

Returns true if the enum definition was successfully added.

bool QOpcUaGenericStructHandler::addCustomStructureDefinition(const QOpcUaStructureDefinition &definition, const QString &typeId, const QString &name, QOpcUa::IsAbstract isAbstract = QOpcUa::IsAbstract::NotAbstract)

Adds the custom structure definition definition to the known types. This can be used to support custom structures the server doesn't expose a StructureDefinition for. The parameters definition, typeId and name are required for proper decoding and encoding. If isAbstract is set, the type can't be encoded and decoded.

Returns true if the structure definition was successfully added.

QOpcUaGenericStructValue QOpcUaGenericStructHandler::createGenericStructValueForTypeId(const QString &typeId)

Returns a generic struct value pre-filled with the struct definition, type id and type name corresponding to typeId. For all mandatory fields, an invalid placeholder QVariant will be inserted.

QOpcUaGenericStructHandler::DataTypeKind QOpcUaGenericStructHandler::dataTypeKindForTypeId(const QString &id) const

Returns the data type kind for the type node id id.

std::optional<QOpcUaGenericStructValue> QOpcUaGenericStructHandler::decode(const QOpcUaExtensionObject &extensionObject) const

Decodes extensionObject to a QOpcUaGenericStructValue. If the decoder fails, std::nullopt is returned.

std::optional<QOpcUaExtensionObject> QOpcUaGenericStructHandler::encode(const QOpcUaGenericStructValue &value)

Returns value encoded as a QOpcUaExtensionObject, or std::nullopt if the value could not be encoded.

QOpcUaEnumDefinition QOpcUaGenericStructHandler::enumDefinitionForTypeId(const QString &id) const

Returns the QOpcUaEnumDefinition for the type node id id. If the node id is unknown or does not belong to an enum type, a default constructed value is returned.

bool QOpcUaGenericStructHandler::initialize()

Starts the data type hierarchy traversal. Success or failure is reported in the initializedChanged signal.

Returns false if the operation can't be started.

`[since 6.7]` bool QOpcUaGenericStructHandler::initialized() const

Returns true if the generic struct handler is initialized.

This function was introduced in Qt 6.7.

`[signal]` void QOpcUaGenericStructHandler::initializedChanged(bool initialized)

This signal is emitted when the initialization process has finished. initialized indicates if the initialization was successful.

bool QOpcUaGenericStructHandler::isAbstractTypeId(const QString &id) const

Returns true if the data type described by id is abstract.

QOpcUaStructureDefinition QOpcUaGenericStructHandler::structureDefinitionForBinaryEncodingId(const QString &id) const

Returns the QOpcUaStructureDefinition for the binary encoding node id id. If the node id is unknown or does not belong to a struct type, a default constructed value is returned.

QOpcUaStructureDefinition QOpcUaGenericStructHandler::structureDefinitionForTypeId(const QString &id) const

Returns the QOpcUaStructureDefinition for the type node id id. If the node id is unknown or does not belong to a struct type, a default constructed value is returned.

QString QOpcUaGenericStructHandler::typeIdForBinaryEncodingId(const QString &id) const

Returns the type node id associated with the binary encoding id id.

QString QOpcUaGenericStructHandler::typeNameForBinaryEncodingId(const QString &id) const

Returns the type name belonging to the binary encoding node id id. If the node id is unknown or does not belong to a struct type, an empty string is returned.

QString QOpcUaGenericStructHandler::typeNameForTypeId(const QString &id) const

Returns the type name belonging to a data type node identified by type node id id. If the node id is unknown, an empty string is returned.

Contents