open62541/doc/datatypes.rst

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);