Data Types ========== Introduction ------------ In open62541, all data types share the same basic API for creation, copying and deletion. The following functions are present for all data types ``T``. ``void T_init(T *ptr)`` Initialize the data type. This is synonymous with zeroing out the memory, i.e. *memset(dataptr, 0, sizeof(T))*. ``T* T_new()`` Allocate and return the memory for the data type. The memory is already initialized. ``UA_StatusCode T_copy(const T *src, T *dst)`` Copy the content of the data type. Returns *UA_STATUSCODE_GOOD* if it succeeded. ``void T_deleteMembers(T *ptr)`` Delete the dynamically allocated content of the data type, but not the data type itself. ``void T_delete(T *ptr)`` Delete the content of the data type and the memory for the data type itself. The builtin data types ---------------------- OPC UA defines 25 builtin data types. All other data types are combinations of the 25 builtin data types. UA_Boolean ^^^^^^^^^^ A two-state logical value (true or false). .. code-block:: c typedef bool UA_Boolean; #define UA_TRUE true #define UA_FALSE false UA_SByte ^^^^^^^^ An integer value between -128 and 127. .. code-block:: c typedef int8_t UA_SByte; UA_Byte ^^^^^^^ An integer value between 0 and 256. .. code-block:: c typedef uint8_t UA_Byte; UA_Int16 ^^^^^^^^ An integer value between -32,768 and 32,767. .. code-block:: c typedef int16_t UA_Int16; UA_UInt16 ^^^^^^^^^ An integer value between 0 and 65,535. .. code-block:: c typedef uint16_t UA_UInt16; UA_Int32 ^^^^^^^^ An integer value between -2,147,483,648 and 2,147,483,647. .. code-block:: c typedef int32_t UA_Int32; UA_UInt32 ^^^^^^^^^ An integer value between 0 and 4,294,967,295. .. code-block:: c typedef uint32_t UA_UInt32; The following functions and definitions are used with UA_UInt32. .. code-block:: c /* do not use for cryptographic entropy */ UA_EXPORT UA_UInt32 UA_UInt32_random(void); UA_Int64 ^^^^^^^^ An integer value between -10,223,372,036,854,775,808 and 9,223,372,036,854,775,807. .. code-block:: c typedef int64_t UA_Int64; UA_UInt64 ^^^^^^^^^ An integer value between 0 and 18,446,744,073,709,551,615. .. code-block:: c typedef uint64_t UA_UInt64; UA_Float ^^^^^^^^ An IEEE single precision (32 bit) floating point value. .. code-block:: c typedef float UA_Float; UA_Double ^^^^^^^^^ An IEEE double precision (64 bit) floating point value. .. code-block:: c typedef double UA_Double; UA_DateTime ^^^^^^^^^^^ An instance in time. A DateTime value is encoded as a 64-bit signed integer which represents the number of 100 nanosecond intervals since January 1, 1601 (UTC). .. code-block:: c typedef UA_Int64 UA_DateTime; The following functions and definitions are used with UA_DateTime. .. code-block:: c UA_DateTime UA_DateTime_now(void); typedef struct UA_DateTimeStruct { UA_UInt16 nanoSec; UA_UInt16 microSec; UA_UInt16 milliSec; UA_UInt16 sec; UA_UInt16 min; UA_UInt16 hour; UA_UInt16 day; UA_UInt16 month; UA_UInt16 year; } UA_DateTimeStruct; UA_DateTimeStruct UA_EXPORT UA_DateTime_toStruct(UA_DateTime time); UA_String UA_EXPORT UA_DateTime_toString(UA_DateTime time); UA_Guid ^^^^^^^ A 16 byte value that can be used as a globally unique identifier. .. code-block:: c typedef struct { UA_UInt32 data1; UA_UInt16 data2; UA_UInt16 data3; UA_Byte data4[8]; } UA_Guid; The following functions and definitions are used with UA_Guid. .. code-block:: c UA_Boolean UA_Guid_equal(const UA_Guid *g1, const UA_Guid *g2); /* do not use for cryptographic entropy */ UA_Guid UA_Guid_random(); UA_String ^^^^^^^^^ A sequence of Unicode characters. See also the section :ref:`array-handling` for the usage of arrays in open62541. .. code-block:: c typedef struct { size_t length; // The length of the string UA_Byte *data; // The string's content (not null-terminated) } UA_String; The following functions and definitions are used with UA_String. .. code-block:: c extern const UA_String UA_STRING_NULL; UA_String UA_STRING(char *chars); #define UA_STRING_ALLOC(CHARS) UA_String_fromChars(CHARS) /** Copies the content on the heap. Returns a null-string when alloc fails */ UA_String UA_String_fromChars(char const src[]); UA_Boolean UA_String_equal(const UA_String *s1, const UA_String *s2); Here's a small example for the usage of UA_String. .. code-block:: c /* The definition of UA_String copied from ua_types.h */ typedef struct { size_t length; ///< The length of the string UA_Byte *data; ///< The string's content (not null-terminated) } UA_String; UA_String s1 = UA_STRING("test1"); /* s1 points to the statically allocated string buffer */ UA_String_init(&s1); /* Reset s1 (no memleak due to the statically allocated buffer) */ UA_String s2 = UA_STRING_ALLOC("test2"); /* s2 points to a new copy of the string buffer (with malloc) */ UA_String_deleteMembers(&s2); /* Free the content of s2, but not s2 itself */ UA_String *s3 = UA_String_new(); /* The string s3 is malloced and initialized */ *s3 = UA_STRING_ALLOC("test3"); /* s3 points to a new copy of the string buffer */ UA_String s4; UA_copy(s3, &s4); /* Copy the content of s3 to s4 */ UA_String_delete(s3); /* Free the string buffer and the string itself */ UA_String_deleteMembers(&s4); /* Again, delete only the string buffer */ UA_ByteString ^^^^^^^^^^^^^ A sequence of octets. .. code-block:: c typedef UA_String UA_ByteString; UA_XmlEelement ^^^^^^^^^^^^^^ An XML element. .. code-block:: c typedef UA_String UA_XmlElement; UA_NodeId ^^^^^^^^^ An identifier for a node in the address space of an OPC UA Server. .. code-block:: c enum UA_NodeIdType { UA_NODEIDTYPE_NUMERIC = 0, // On the wire, this can be 0, 1 or 2 (shortened numeric nodeids) UA_NODEIDTYPE_STRING = 3, UA_NODEIDTYPE_GUID = 4, UA_NODEIDTYPE_BYTESTRING = 5 }; typedef struct { UA_UInt16 namespaceIndex; enum UA_NodeIdType identifierType; union { UA_UInt32 numeric; UA_String string; UA_Guid guid; UA_ByteString byteString; } identifier; } UA_NodeId; The following functions and definitions are used with UA_NodeId. .. code-block:: c UA_Boolean UA_NodeId_isNull(const UA_NodeId *p); UA_Boolean UA_NodeId_equal(const UA_NodeId *n1, const UA_NodeId *n2); extern const UA_NodeId UA_NODEID_NULL; UA_NodeId UA_NODEID_NUMERIC(UA_UInt16 nsIndex, UA_Int32 identifier); UA_NodeId UA_NODEID_STRING(UA_UInt16 nsIndex, char *chars) { UA_NodeId UA_NODEID_STRING_ALLOC(UA_UInt16 nsIndex, const char *chars); UA_NodeId UA_NODEID_GUID(UA_UInt16 nsIndex, UA_Guid guid); UA_NodeId UA_NODEID_BYTESTRING(UA_UInt16 nsIndex, char *chars); UA_NodeId UA_NODEID_BYTESTRING_ALLOC(UA_UInt16 nsIndex, const char *chars); UA_ExpandedNodeId ^^^^^^^^^^^^^^^^^ A NodeId that allows the namespace URI to be specified instead of an index. .. code-block:: c typedef struct { UA_NodeId nodeId; UA_String namespaceUri; UA_UInt32 serverIndex; } UA_ExpandedNodeId; The following functions and definitions are used with UA_ExpandedNodeId. .. code-block:: c UA_ExpandedNodeId UA_EXPANDEDNODEID_NUMERIC(UA_UInt16 nsIndex, UA_Int32 identifier); UA_ExpandedNodeId UA_EXPANDEDNODEID_STRING(UA_UInt16 nsIndex, char *chars); UA_ExpandedNodeId UA_EXPANDEDNODEID_STRING_ALLOC(UA_UInt16 nsIndex, const char *chars); UA_ExpandedNodeId UA_EXPANDEDNODEID_STRING_GUID(UA_UInt16 nsIndex, UA_Guid guid); UA_ExpandedNodeId UA_EXPANDEDNODEID_BYTESTRING(UA_UInt16 nsIndex, char *chars); UA_ExpandedNodeId UA_EXPANDEDNODEID_BYTESTRING_ALLOC(UA_UInt16 nsIndex, const char *chars); UA_QualifiedName ^^^^^^^^^^^^^^^^ A name qualified by a namespace. .. code-block:: c typedef struct { UA_UInt16 namespaceIndex; UA_String name; } UA_QualifiedName; The following functions and definitions are used with UA_QualifiedName. .. code-block:: c UA_QualifiedName UA_QUALIFIEDNAME(UA_UInt16 nsIndex, char *chars); UA_QualifiedName UA_QUALIFIEDNAME_ALLOC(UA_UInt16 nsIndex, const char *chars); UA_LocalizedText ^^^^^^^^^^^^^^^^ Human readable text with an optional locale identifier. .. code-block:: c typedef struct { UA_String locale; UA_String text; } UA_LocalizedText; The following functions and definitions are used with UA_LocalizedText. .. code-block:: c UA_LocalizedText UA_LOCALIZEDTEXT(char *locale, char *text); UA_LocalizedText UA_LOCALIZEDTEXT_ALLOC(const char *locale, const char *text); UA_ExtensionObject ^^^^^^^^^^^^^^^^^^ A structure that contains an application specific data type that may not be recognized by the receiver. .. code-block:: c typedef struct { enum { UA_EXTENSIONOBJECT_ENCODED_NOBODY = 0, UA_EXTENSIONOBJECT_ENCODED_BYTESTRING = 1, UA_EXTENSIONOBJECT_ENCODED_XML = 2, UA_EXTENSIONOBJECT_DECODED = 3, ///< There is a pointer to the decoded data UA_EXTENSIONOBJECT_DECODED_NODELETE = 4 ///< Don't delete the decoded data at the lifecycle end } encoding; union { struct { UA_NodeId typeId; ///< The nodeid of the datatype UA_ByteString body; ///< The bytestring of the encoded data } encoded; struct { const UA_DataType *type; void *data; } decoded; } content; } UA_ExtensionObject; UA_Variant ^^^^^^^^^^ Stores (arrays of) any data type. Please see section :ref:`generic-handling` for the usage of UA_DataType. The semantics of the arrayLength field is explained in section :ref:`array-handling`. .. code-block:: c typedef struct { const UA_DataType *type; // The data type description enum { UA_VARIANT_DATA, /* The data has the same lifecycle as the variant */ UA_VARIANT_DATA_NODELETE, /* The data is "borrowed" by the variant and shall not be deleted at the end of the variant's lifecycle. */ } storageType; size_t arrayLength; // The number of elements in the data array void *data; // Points to the scalar or array data size_t arrayDimensionsSize; // The number of dimensions the data-array has UA_UInt32 *arrayDimensions; // The length of each dimension of the data-array } UA_Variant; /* NumericRanges are used to indicate subsets of a (multidimensional) variant * array. NumericRange has no official type structure in the standard. On the * wire, it only exists as an encoded string, such as "1:2,0:3,5". The colon * separates min/max index and the comma separates dimensions. A single value * indicates a range with a single element (min==max). */ typedef struct { size_t dimensionsSize; struct UA_NumericRangeDimension { UA_UInt32 min; UA_UInt32 max; } *dimensions; } UA_NumericRange; The following functions and definitions are used with UA_Variant. .. code-block:: c /** * Returns true if the variant contains a scalar value. Note that empty * variants contain an array of length -1 (undefined). * * @param v The variant * @return Does the variant contain a scalar value. */ UA_Boolean UA_Variant_isScalar(const UA_Variant *v); /** * Set the variant to a scalar value that already resides in memory. The value * takes on the lifecycle of the variant and is deleted with it. * * @param v The variant * @param p A pointer to the value data * @param type The datatype of the value in question */ UA_Variant_setScalar(UA_Variant *v, void * UA_RESTRICT p, const UA_DataType *type); /** * Set the variant to a scalar value that is copied from an existing variable. * * @param v The variant * @param p A pointer to the value data * @param type The datatype of the value * @return Indicates whether the operation succeeded or returns an error code */ UA_StatusCode UA_Variant_setScalarCopy(UA_Variant *v, const void *p, const UA_DataType *type); /** * Set the variant to an array that already resides in memory. The array takes * on the lifecycle of the variant and is deleted with it. * * @param v The variant * @param array A pointer to the array data * @param arraySize The size of the array * @param type The datatype of the array */ void UA_Variant_setArray(UA_Variant *v, void * UA_RESTRICT array, size_t arraySize, const UA_DataType *type); /** * Set the variant to an array that is copied from an existing array. * * @param v The variant * @param array A pointer to the array data * @param arraySize The size of the array * @param type The datatype of the array * @return Indicates whether the operation succeeded or returns an error code */ UA_StatusCode UA_Variant_setArrayCopy(UA_Variant *v, const void *array, size_t arraySize, const UA_DataType *type); /** * Copy the variant, but use only a subset of the (multidimensional) array * into a variant. Returns an error code if the variant is not an array or if * the indicated range does not fit. * * @param src The source variant * @param dst The target variant * @param range The range of the copied data * @return Returns UA_STATUSCODE_GOOD or an error code */ UA_StatusCode UA_Variant_copyRange(const UA_Variant *src, UA_Variant *dst, const UA_NumericRange range); /** * Insert a range of data into an existing variant. The data array can't be * reused afterwards if it contains types without a fixed size (e.g. strings) * since the members are moved into the variant and take on its lifecycle. * * @param v The variant * @param dataArray The data array. The type must match the variant * @param dataArraySize The length of the data array. This is checked to match the range size. * @param range The range of where the new data is inserted * @return Returns UA_STATUSCODE_GOOD or an error code */ UA_StatusCode UA_Variant_setRange(UA_Variant *v, void * UA_RESTRICT array, size_t arraySize, const UA_NumericRange range); /** * Deep-copy a range of data into an existing variant. * * @param v The variant * @param dataArray The data array. The type must match the variant * @param dataArraySize The length of the data array. This is checked to match the range size. * @param range The range of where the new data is inserted * @return Returns UA_STATUSCODE_GOOD or an error code */ UA_StatusCode UA_Variant_setRangeCopy(UA_Variant *v, const void *array, size_t arraySize, const UA_NumericRange range); UA_DataValue ^^^^^^^^^^^^ A data value with an associated status code and timestamps. .. code-block:: c typedef struct { UA_Boolean hasValue : 1; UA_Boolean hasStatus : 1; UA_Boolean hasSourceTimestamp : 1; UA_Boolean hasServerTimestamp : 1; UA_Boolean hasSourcePicoseconds : 1; UA_Boolean hasServerPicoseconds : 1; UA_Variant value; UA_StatusCode status; UA_DateTime sourceTimestamp; UA_Int16 sourcePicoseconds; UA_DateTime serverTimestamp; UA_Int16 serverPicoseconds; } UA_DataValue; UA_DiagnosticInfo ^^^^^^^^^^^^^^^^^ A structure that contains detailed error and diagnostic information associated with a StatusCode. .. code-block:: c typedef struct UA_DiagnosticInfo { UA_Boolean hasSymbolicId : 1; UA_Boolean hasNamespaceUri : 1; UA_Boolean hasLocalizedText : 1; UA_Boolean hasLocale : 1; UA_Boolean hasAdditionalInfo : 1; UA_Boolean hasInnerStatusCode : 1; UA_Boolean hasInnerDiagnosticInfo : 1; UA_Int32 symbolicId; UA_Int32 namespaceUri; UA_Int32 localizedText; UA_Int32 locale; UA_String additionalInfo; UA_StatusCode innerStatusCode; struct UA_DiagnosticInfo *innerDiagnosticInfo; } UA_DiagnosticInfo; .. _generic-handling: Generic Data Type Handling -------------------------- All standard-defined data types are described with an ``UA_DataType`` structure. In addition to the 25 builtin data types, OPC UA defines many more. But they are mere combinations of the builtin data types. We handle all types in a unified way by storing their internal structure. So it is not necessary to define specialized functions for all additional types. The ``UA_TYPES`` array contains the description of every standard-defined data type. .. code-block:: c extern const UA_DataType UA_TYPES[UA_TYPES_COUNT]; The following is an excerpt from ``ua_types_generated.h`` with the definition of OPC UA read requests. This file is auto-generated from the XML-description of the OPC UA data types that is part of the ISO/IEC 62541 standard. .. code-block:: c typedef struct { UA_RequestHeader requestHeader; UA_Double maxAge; UA_TimestampsToReturn timestampsToReturn; size_t nodesToReadSize; UA_ReadValueId *nodesToRead; } UA_ReadRequest; #define UA_TYPES_READREQUEST 118 static UA_INLINE void UA_ReadRequest_init(UA_ReadRequest *p) { memset(p, 0, sizeof(UA_ReadRequest)); } static UA_INLINE void UA_ReadRequest_delete(UA_ReadRequest *p) { UA_delete(p, &UA_TYPES[UA_TYPES_READREQUEST]); } static UA_INLINE void UA_ReadRequest_deleteMembers(UA_ReadRequest *p) { UA_deleteMembers(p, &UA_TYPES[UA_TYPES_READREQUEST]); } static UA_INLINE UA_ReadRequest * UA_ReadRequest_new(void) { return (UA_ReadRequest*) UA_new(&UA_TYPES[UA_TYPES_READREQUEST]); } static UA_INLINE UA_StatusCode UA_ReadRequest_copy(const UA_ReadRequest *src, UA_ReadRequest *dst) { return UA_copy(src, dst, &UA_TYPES[UA_TYPES_READREQUEST]); } .. _array-handling: Array Handling -------------- In OPC UA, all arrays can be undefined, have length 0 or a positive length. In data structures, all arrays are represented by a ``size_t`` length field and an appropriate pointer directly afterwards. In order to distinguish between undefined and length-zero arrays, we define the following. .. code-block:: c #define UA_EMPTY_ARRAY_SENTINEL ((void*)0x01) - size == 0 and data == NULL: The array is undefined - size == 0 and data == ``UA_EMPTY_ARRAY_SENTINEL``: The array has length 0 - size > 0: The array at the given memory address has the given size The following functions are defined for array handling. .. code-block:: c /** * Allocates and initializes an array of variables of a specific type * * @param size The requested array length * @param type The datatype description * @return Returns the memory location of the variable or (void*)0 if no memory could be allocated */ void * UA_Array_new(size_t size, const UA_DataType *type); /** * Allocates and copies an array. dst is set to (void*)0 if not enough memory is available. * * @param src The memory location of the source array * @param src_size The size of the array * @param dst The location of the pointer to the new array * @param type The datatype of the array members * @return Returns whether copying succeeded */ UA_StatusCode UA_Array_copy(const void *src, size_t src_size, void **dst, const UA_DataType *type); /** * Deletes an array. * * @param p The memory location of the array * @param size The size of the array * @param type The datatype of the array members */ void UA_Array_delete(void *p, size_t size, const UA_DataType *type);