open62541/doc/datatypes.rst

Data Types Introduction
=======================
In open62541, all data types share the same basic API for creation, copying and deletion. Assume that *T* is the data type in question.

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.

Here's a small example for the UA_String data type. UA_String will be introduced in more detail later on, but you should be able to follow the example already.

.. 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 */

Generic Data Type Handling
==========================

All data types are combinations of the 25 builtin data types show below. Types
are described in the UA_DataType structure.

.. doxygenstruct:: UA_DataType
   :members:

.. c:var:: const UA_DataType UA_TYPES[UA_TYPES_COUNT]

  The datatypes defined in the standard are stored in the ``UA_TYPES`` array.
  A typical function call is ``UA_Array_new(&data_ptr, 20, &UA_TYPES[UA_TYPES_STRING])``.

.. doxygenfunction:: UA_new
.. doxygenfunction:: UA_init
.. doxygenfunction:: UA_copy
.. doxygenfunction:: UA_deleteMembers
.. doxygenfunction:: UA_delete

For all datatypes, there are also macros with syntactic sugar over calling the
generic functions with a pointer into the ``UA_TYPES`` array.

.. c:function:: <typename>_new()

  Allocates the memory for the type and runs _init on the returned variable.
  Returns null if no memory could be allocated.

.. c:function:: <typename>_init(<typename> *value)

  Sets all members of the type to a default value, usually zero. Arrays (e.g.
  for strings) are set to a length of -1.

.. c:function:: <typename>_copy(<typename> *src, <typename> *dst)

  Copies a datatype. This performs a deep copy iterating over the members.
  Copying into variants with an external data source is not permitted. If
  copying fails, a deleteMembers is performed and an error code returned.

.. c:function:: <typename>_deleteMembers(<typename> *value)

   Frees the memory of dynamically sized members of a datatype (e.g. arrays).

.. c:function:: <typename>_delete(<typename> *value)

   Frees the memory of the datatype and its dynamically allocated members.

Array Handling
--------------
   
.. doxygenfunction:: UA_Array_new
.. doxygenfunction:: UA_Array_copy
.. doxygenfunction:: UA_Array_delete

Builtin Data Types
------------------

Number-Types
^^^^^^^^^^^^

.. doxygentypedef:: UA_Boolean
.. doxygentypedef:: UA_SByte
.. doxygentypedef:: UA_Byte
.. doxygentypedef:: UA_Int16
.. doxygentypedef:: UA_UInt16
.. doxygentypedef:: UA_Int32
.. doxygentypedef:: UA_UInt32
.. doxygentypedef:: UA_Int64
.. doxygentypedef:: UA_UInt64
.. doxygentypedef:: UA_Float
.. doxygentypedef:: UA_Double

UA_String
^^^^^^^^^
.. doxygenstruct:: UA_String
  :members:

.. c:macro:: UA_STRING_NULL

  The empty string

.. c:macro:: UA_STRING(CHARS)
     
  Creates an UA_String from an array of ``char``. The characters are not copied
  on the heap. Instead, the string points into the existing array.

.. c:macro:: UA_STRING_ALLOC(CHARS)
     
  Creates an UA_String from an array of ``char``. The characters are copied on
  the heap.

.. doxygenfunction:: UA_String_equal
.. doxygenfunction:: UA_String_copyprintf

UA_DateTime
^^^^^^^^^^^
.. doxygentypedef:: UA_DateTime
.. doxygenfunction:: UA_DateTime_now(void)
.. doxygenfunction:: UA_DateTime_toString
.. doxygenfunction:: UA_DateTime_toStruct

UA_Guid
^^^^^^^
.. doxygenstruct:: UA_Guid
.. doxygenfunction:: UA_Guid_equal
.. doxygenfunction:: UA_Guid_random
   
UA_ByteString
^^^^^^^^^^^^^
Bytestring are just a redefinition of strings. The semantic difference is that
ByteStrings may hold non-UTF8 data.

.. doxygentypedef:: UA_ByteString

.. c:macro:: UA_BYTESTRING_NULL

   The empty ByteString

.. c:function:: UA_Boolean UA_ByteString_equal(const UA_ByteString *s1, const UA_ByteString *s2)

   Compares two ByteStrings.
   
UA_XmlElement
^^^^^^^^^^^^^
XmlElements are just a redefinition of strings.

.. doxygentypedef:: UA_XmlElement

UA_NodeId
^^^^^^^^^
.. doxygenstruct:: UA_NodeId
  :members:

.. doxygenfunction:: UA_NodeId_equal
.. doxygenfunction:: UA_NodeId_isNull

.. c:macro:: UA_NODEID_NULL

  The null NodeId

.. c:macro:: UA_NODEID_NUMERIC(NSID, NUMERICID)
.. c:macro:: UA_NODEID_STRING(NSID, CHARS)
.. c:macro:: UA_NODEID_STRING_ALLOC(NSID, CHARS)
.. c:macro:: UA_NODEID_GUID(NSID, GUID)
.. c:macro:: UA_NODEID_BYTESTRING(NSID, CHARS)
.. c:macro:: UA_NODEID_BYTESTRING_ALLOC(NSID, CHARS)

UA_ExpandedNodeId
^^^^^^^^^^^^^^^^^
.. doxygenstruct:: UA_ExpandedNodeId
  :members:

.. doxygenfunction:: UA_ExpandedNodeId_isNull
.. c:macro:: UA_EXPANDEDNODEID_NUMERIC(NSID, NUMERICID)
  
UA_StatusCode
^^^^^^^^^^^^^
Many functions in open62541 return either ``UA_STATUSCODE_GOOD`` or an error code.

.. doxygentypedef:: UA_StatusCode

UA_QualifiedName
^^^^^^^^^^^^^^^^   
.. doxygenstruct:: UA_QualifiedName
  :members:

.. c:macro:: UA_QUALIFIEDNAME(NSID, CHARS)
.. c:macro:: UA_QUALIFIEDNAME_ALLOC(NSID, CHARS)
  
UA_LocalizedText
^^^^^^^^^^^^^^^^
.. doxygenstruct:: UA_LocalizedText
  :members:

.. c:macro:: UA_LOCALIZEDTEXT(LOCALE, TEXT)
   Takes two arrays of ``char`` as the input.

.. c:macro:: UA_LOCALIZEDTEXT_ALLOC(LOCALE, TEXT)
  
UA_ExtensionObject
^^^^^^^^^^^^^^^^^^

.. doxygenstruct:: UA_ExtensionObject
  :members:

UA_DataValue
^^^^^^^^^^^^

.. doxygenstruct:: UA_DataValue
  :members:
  :undoc-members:

UA_Variant
^^^^^^^^^^

.. doxygenstruct:: UA_Variant
  :members:

.. doxygenfunction:: UA_Variant_isScalar
.. doxygenfunction:: UA_Variant_setScalar
.. doxygenfunction:: UA_Variant_setScalarCopy
.. doxygenfunction:: UA_Variant_setArray
.. doxygenfunction:: UA_Variant_setArrayCopy

.. doxygenstruct:: UA_NumericRange
   :undoc-members:

.. doxygenfunction:: UA_Variant_setRange
.. doxygenfunction:: UA_Variant_setRangeCopy
        
UA_DiagnosticInfo
^^^^^^^^^^^^^^^^^

.. doxygenstruct:: UA_DiagnosticInfo
  :members:
  :undoc-members: