open62541/src/ua_types.h

#ifndef UA_TYPES_H_
#define UA_TYPES_H_

#include <stdint.h>

/**
 * @defgroup types Datatypes
 *
 * @brief This module describes the datatypes used in OPC UA. There is a
 * division into built-in datatypes (integers, strings, etc.) and more complex
 * datatypes that are comprise of built-in datatypes (structs defined in the OPC
 * UA standard).
 *
 * All datatypes follow the same schema in the naming of relevant functions.
 *
 * - <type>_init: Sets all values to a "safe" standard. For example, if the
 *     datatype contains a string-element, its size will be set to zero.
 *
 * - <type>_new: Allocates the memory for the type and runs <type>_init on the
 *     returned pointer.
 *
 * - <type>_copy: Copies a datatype. This performs a deep copy that iterates
 *    over the members.
 *
 * - <type>_delete: Frees the memory where the datatype was stored.
 *
 * - <type>_deleteMembers: Frees the memory of dynamically sized members (e.g. a
     string) of a datatype. This is useful when the datatype was allocated on
     the stack, whereas the dynamically sized members is heap-allocated.
 *
 * @{
 */

/* Function return values */
#define UA_SUCCESS 0
#define UA_NO_ERROR UA_SUCCESS
#define UA_ERROR (0x01 << 31)
#define UA_ERR_INCONSISTENT (UA_ERROR | (0x01 << 1))
#define UA_ERR_INVALID_VALUE (UA_ERROR | (0x01 << 2))
#define UA_ERR_NO_MEMORY (UA_ERROR | (0x01 << 3))
#define UA_ERR_NOT_IMPLEMENTED (UA_ERROR | (0x01 << 4))

/* Boolean values and null */
#define UA_TRUE (42 == 42)
#define TRUE UA_TRUE
#define UA_FALSE (!UA_TRUE)
#define FALSE UA_FALSE

/* Compare values */
#define UA_EQUAL 0
#define UA_NOT_EQUAL (!UA_EQUAL)

/** @brief A two-state logical value (true or false). */
typedef _Bool UA_Boolean;

/** @brief An integer value between −128 and 127. */
typedef int8_t UA_SByte;

/** @brief An integer value between 0 and 256. */
typedef uint8_t UA_Byte;

/** @brief An integer value between −32 768 and 32 767. */
typedef int16_t UA_Int16;

/** @brief An integer value between 0 and 65 535. */
typedef uint16_t UA_UInt16;

/** @brief An integer value between −2 147 483 648 and 2 147 483 647. */
typedef int32_t UA_Int32;

/** @brief An integer value between 0 and 429 4967 295. */
typedef uint32_t UA_UInt32;

/** @brief An integer value between −9 223 372 036 854 775 808 and 9 223 372 036 854 775 807 */
typedef int64_t UA_Int64;

/** @brief An integer value between 0 and 18 446 744 073 709 551 615. */
typedef uint64_t UA_UInt64;

/** @brief An IEEE single precision (32 bit) floating point value. */
typedef float UA_Float;

/** @brief An IEEE double precision (64 bit) floating point value. */
typedef double UA_Double;

/** @brief A sequence of Unicode characters. */
typedef struct UA_String {
	UA_Int32 length;
	UA_Byte *data;
} UA_String;

/** @brief An instance in time. */
typedef UA_Int64 UA_DateTime; //100 nanosecond resolution

/** @brief A 16 byte value that can be used as a globally unique identifier. */
typedef struct UA_Guid {
	UA_UInt32 data1;
	UA_UInt16 data2;
	UA_UInt16 data3;
	UA_Byte   data4[8];
} UA_Guid;

/** @brief A sequence of octets. */
typedef struct UA_ByteString {
	UA_Int32 length;
	UA_Byte *data;
} UA_ByteString;

/** @brief An XML element. */
typedef struct UA_ByteString UA_XmlElement;

/** @brief An identifier for a node in the address space of an OPC UA Server. */
typedef struct UA_NodeId {
	UA_Byte encodingByte;       //enum BID_NodeIdEncodingValuesType
	UA_UInt16 namespace;
	union {
		UA_UInt32     numeric;
		UA_String     string;
		UA_Guid       guid;
		UA_ByteString byteString;
	} identifier;
} UA_NodeId;

#define UA_NODEIDTYPE_NAMESPACE_URI_FLAG 0x80
#define UA_NODEIDTYPE_SERVERINDEX_FLAG 0x40
#define UA_NODEIDTYPE_MASK (~(UA_NODEIDTYPE_NAMESPACE_URI_FLAG | UA_NODEIDTYPE_SERVERINDEX_FLAG))

/** @brief A NodeId that allows the namespace URI to be specified instead of an index. */
typedef struct UA_ExpandedNodeId {
	UA_NodeId nodeId;
	UA_String namespaceUri;
	UA_UInt32 serverIndex;
} UA_ExpandedNodeId;

/** @brief A numeric identifier for a error or condition that is associated with a value or an operation. */
typedef UA_UInt32 UA_StatusCode; // StatusCodes aren't an enum(=int) since 32 unsigned bits are needed. See also ua_statuscodes.h */

/** @brief A name qualified by a namespace. */
typedef struct UA_QualifiedName {
	UA_UInt16 namespaceIndex;
	UA_String name;
} UA_QualifiedName;

/** @brief Human readable text with an optional locale identifier. */
typedef struct UA_LocalizedText {
	UA_Byte   encodingMask;
	UA_String locale;
	UA_String text;
} UA_LocalizedText;

enum UA_LOCALIZEDTEXT_ENCODINGMASKTYPE_enum {
	UA_LOCALIZEDTEXT_ENCODINGMASKTYPE_LOCALE = 0x01,
	UA_LOCALIZEDTEXT_ENCODINGMASKTYPE_TEXT   = 0x02
};

/** @brief A structure that contains an application specific data type that may not be recognized by the receiver. */
typedef struct UA_ExtensionObject {
	UA_NodeId     typeId;
	UA_Byte       encoding;     // Type of the enum UA_ExtensionObjectEncodingMaskType
	UA_ByteString body;         // contains either the bytestring or a pointer to the memory-object
} UA_ExtensionObject;

enum UA_ExtensionObject_EncodingMaskType_enum {
	UA_EXTENSIONOBJECT_ENCODINGMASK_NOBODYISENCODED  = 0x00,
	UA_EXTENSIONOBJECT_ENCODINGMASK_BODYISBYTESTRING = 0x01,
	UA_EXTENSIONOBJECT_ENCODINGMASK_BODYISXML        = 0x02
};

struct UA_VTable_Entry; // forwards declaration
typedef struct UA_VTable_Entry UA_VTable_Entry;

/** @brief A union of all of the types specified above. */
typedef struct UA_Variant {
	UA_VTable_Entry *vt;          // internal entry into vTable
	UA_Byte encodingMask;         // Type of UA_Variant_EncodingMaskType_enum
	UA_Int32         arrayLength; // total number of elements
	UA_Int32         arrayDimensionsLength;
	UA_Int32        *arrayDimensions;
	void *data;
} UA_Variant;

/* VariantBinaryEncoding - Part: 6, Chapter: 5.2.2.16, Page: 22 */
enum UA_VARIANT_ENCODINGMASKTYPE_enum {
	UA_VARIANT_ENCODINGMASKTYPE_TYPEID_MASK = 0x3F,            // bits 0:5
	UA_VARIANT_ENCODINGMASKTYPE_DIMENSIONS  = (0x01 << 6),     // bit 6
	UA_VARIANT_ENCODINGMASKTYPE_ARRAY       = (0x01 << 7)      // bit 7
};

/** @brief A data value with an associated status code and timestamps. */
typedef struct UA_DataValue {
	UA_Byte       encodingMask;
	UA_Variant    value;
	UA_StatusCode status;
	UA_DateTime   sourceTimestamp;
	UA_Int16      sourcePicoseconds;
	UA_DateTime   serverTimestamp;
	UA_Int16      serverPicoseconds;
} UA_DataValue;

enum UA_DATAVALUE_ENCODINGMASKTYPE_enum {
	UA_DATAVALUE_ENCODINGMASK_VARIANT           = 0x01,
	UA_DATAVALUE_ENCODINGMASK_STATUSCODE        = 0x02,
	UA_DATAVALUE_ENCODINGMASK_SOURCETIMESTAMP   = 0x04,
	UA_DATAVALUE_ENCODINGMASK_SERVERTIMESTAMP   = 0x08,
	UA_DATAVALUE_ENCODINGMASK_SOURCEPICOSECONDS = 0x10,
	UA_DATAVALUE_ENCODINGMASK_SERVERPICOSECONDS = 0x20
};

/** @brief A structure that contains detailed error and diagnostic information associated with a StatusCode. */
typedef struct UA_DiagnosticInfo {
	UA_Byte       encodingMask;     // Type of the Enum UA_DIAGNOSTICINFO_ENCODINGMASKTYPE
	UA_Int32      symbolicId;
	UA_Int32      namespaceUri;
	UA_Int32      localizedText;
	UA_Int32      locale;
	UA_String     additionalInfo;
	UA_StatusCode innerStatusCode;
	struct UA_DiagnosticInfo *innerDiagnosticInfo;
} UA_DiagnosticInfo;

enum UA_DIAGNOSTICINFO_ENCODINGMASKTYPE_enum {
	UA_DIAGNOSTICINFO_ENCODINGMASK_SYMBOLICID          = 0x01,
	UA_DIAGNOSTICINFO_ENCODINGMASK_NAMESPACE           = 0x02,
	UA_DIAGNOSTICINFO_ENCODINGMASK_LOCALIZEDTEXT       = 0x04,
	UA_DIAGNOSTICINFO_ENCODINGMASK_LOCALE              = 0x08,
	UA_DIAGNOSTICINFO_ENCODINGMASK_ADDITIONALINFO      = 0x10,
	UA_DIAGNOSTICINFO_ENCODINGMASK_INNERSTATUSCODE     = 0x20,
	UA_DIAGNOSTICINFO_ENCODINGMASK_INNERDIAGNOSTICINFO = 0x40
};

/** @brief Type use internally to denote an invalid datatype. */
typedef void UA_InvalidType;

/*************/
/* Functions */
/*************/

#define UA_TYPE_PROTOTYPES(TYPE)             \
    UA_Int32 TYPE##_new(TYPE **p);           \
    UA_Int32 TYPE##_init(TYPE * p);          \
    UA_Int32 TYPE##_delete(TYPE * p);        \
    UA_Int32 TYPE##_deleteMembers(TYPE * p); \
    UA_Int32 TYPE##_copy(const TYPE *src, TYPE *dst);

/* Functions for all types */
UA_TYPE_PROTOTYPES(UA_Boolean)
UA_TYPE_PROTOTYPES(UA_SByte)
UA_TYPE_PROTOTYPES(UA_Byte)
UA_TYPE_PROTOTYPES(UA_Int16)
UA_TYPE_PROTOTYPES(UA_UInt16)
UA_TYPE_PROTOTYPES(UA_Int32)
UA_TYPE_PROTOTYPES(UA_UInt32)
UA_TYPE_PROTOTYPES(UA_Int64)
UA_TYPE_PROTOTYPES(UA_UInt64)
UA_TYPE_PROTOTYPES(UA_Float)
UA_TYPE_PROTOTYPES(UA_Double)
UA_TYPE_PROTOTYPES(UA_String)
UA_TYPE_PROTOTYPES(UA_DateTime)
UA_TYPE_PROTOTYPES(UA_Guid)
UA_TYPE_PROTOTYPES(UA_ByteString)
UA_TYPE_PROTOTYPES(UA_XmlElement)
UA_TYPE_PROTOTYPES(UA_NodeId)
UA_TYPE_PROTOTYPES(UA_ExpandedNodeId)
UA_TYPE_PROTOTYPES(UA_StatusCode)
UA_TYPE_PROTOTYPES(UA_QualifiedName)
UA_TYPE_PROTOTYPES(UA_LocalizedText)
UA_TYPE_PROTOTYPES(UA_ExtensionObject)
UA_TYPE_PROTOTYPES(UA_DataValue)
UA_TYPE_PROTOTYPES(UA_Variant)
UA_TYPE_PROTOTYPES(UA_DiagnosticInfo)
UA_TYPE_PROTOTYPES(UA_InvalidType)

/* String */
UA_Int32 UA_String_copycstring(char const *src, UA_String *dst);
UA_Int32 UA_String_copyprintf(char const *fmt, UA_String *dst, ...);
UA_Int32 UA_String_equal(const UA_String *string1, const UA_String *string2);
void UA_String_printf(char const *label, const UA_String *string);
void UA_String_printx(char const *label, const UA_String *string);
void UA_String_printx_hex(char const *label, const UA_String *string);

/* DateTime */
UA_DateTime UA_DateTime_now();
typedef struct UA_DateTimeStruct {
	UA_Int16 nanoSec;
	UA_Int16 microSec;
	UA_Int16 milliSec;
	UA_Int16 sec;
	UA_Int16 min;
	UA_Int16 hour;
	UA_Int16 day;
	UA_Int16 mounth;
	UA_Int16 year;
} UA_DateTimeStruct;
UA_DateTimeStruct UA_DateTime_toStruct(UA_DateTime time);
UA_Int32 UA_DateTime_toString(UA_DateTime time, UA_String *timeString);

/* Guid */
UA_Int32 UA_Guid_equal(const UA_Guid *g1, const UA_Guid *g2);

/* ByteString */
UA_Int32 UA_ByteString_equal(const UA_ByteString *string1, const UA_ByteString *string2);
UA_Int32 UA_ByteString_newMembers(UA_ByteString *p, UA_Int32 length);
void UA_ByteString_printf(char *label, const UA_ByteString *string);
void UA_ByteString_printx(char *label, const UA_ByteString *string);
void UA_ByteString_printx_hex(char *label, const UA_ByteString *string);

/* NodeId */
UA_Int32 UA_NodeId_equal(const UA_NodeId *n1, const UA_NodeId *n2);
void UA_NodeId_printf(char *label, const UA_NodeId *node);
UA_Boolean UA_NodeId_isNull(const UA_NodeId *p);
UA_Int16 UA_NodeId_getNamespace(UA_NodeId const *id);
UA_Int16 UA_NodeId_getIdentifier(UA_NodeId const *id);
UA_Boolean UA_NodeId_isBasicType(UA_NodeId const *id);

/* ExpandedNodeId */
UA_Boolean UA_ExpandedNodeId_isNull(const UA_ExpandedNodeId *p);

/* QualifiedName */
void UA_QualifiedName_printf(char const *label, const UA_QualifiedName *qn);

/* LocalizedText */
UA_Int32 UA_LocalizedText_copycstring(char const *src, UA_LocalizedText *dst);

/* Variant */
UA_Int32 UA_Variant_copySetValue(UA_Variant *v, UA_Int32 type, const void *data);
UA_Int32 UA_Variant_copySetArray(UA_Variant *v, UA_Int32 type_id, UA_Int32 arrayLength, UA_UInt32 elementSize,
                                 const void *array);

/** @brief Functions UA_Variant_borrowSetValue and ..Array allow to define
   variants whose payload will not be deleted. This is achieved by a second
   vtable. The functionality can be used e.g. when UA_VariableNodes point into a
   "father" structured object that is stored in an UA_VariableNode itself. */
UA_Int32 UA_Variant_borrowSetValue(UA_Variant *v, UA_Int32 type, const void *data);
UA_Int32 UA_Variant_borrowSetArray(UA_Variant *v, UA_Int32 type, UA_Int32 arrayLength, const void *data);

/* Array operations */
UA_Int32 UA_Array_new(void **p, UA_Int32 noElements, UA_Int32 type);
UA_Int32 UA_Array_init(void *p, UA_Int32 noElements, UA_Int32 type);
UA_Int32 UA_Array_delete(void *p, UA_Int32 noElements, UA_Int32 type);

/* @brief The destination array is allocated according to noElements. */
UA_Int32 UA_Array_copy(const void *src, UA_Int32 noElements, UA_Int32 type, void **dst);

/**********/
/* VTable */
/**********/

/* @brief Returns the size of the encoded element.*/
typedef UA_Int32 (*UA_calcSize)(const void *p);

/* @brief The encoding function allocates the target bytestring. */
typedef UA_Int32 (*UA_encode)(const void *src, UA_ByteString *dst, UA_UInt32 *offset);

/* @brief The decoding function decodes a ByteString into an UA datatype. */
typedef UA_Int32 (*UA_decode)(UA_ByteString *src, UA_UInt32 *offset, void *dst);

typedef struct UA_Encoding {
	UA_calcSize calcSize;
	UA_encode   encode;
	UA_decode   decode;
} UA_Encoding;

struct UA_VTable_Entry {
	UA_NodeId   typeId;
	UA_Byte    *name;
	UA_Int32    (*new)(void **p);
	UA_Int32    (*init)(void *p);
	UA_Int32    (*copy)(void const *src, void *dst);
	UA_Int32    (*delete)(void *p);
	UA_Int32    (*deleteMembers)(void *p);
	UA_UInt32   memSize;      // size of the struct only in memory (no dynamic components)
	UA_Boolean  dynMembers;   // does the type contain members that are dynamically
	                          // allocated (strings, ..)? Otherwise, the size on
	                          // the wire == size in memory.
	UA_Encoding encodings[2]; // binary, xml, ...
};

typedef UA_Int32 (*UA_nodeIdToVTableIndex)(const UA_NodeId *id);
typedef struct UA_VTable {
	UA_nodeIdToVTableIndex getTypeIndex;
	UA_VTable_Entry       *types;
} UA_VTable;

/***********************************/
/* Macros for type implementations */
/***********************************/

#define UA_TYPE_DEFAULT(TYPE)            \
    UA_TYPE_DELETE_DEFAULT(TYPE)         \
    UA_TYPE_DELETEMEMBERS_NOACTION(TYPE) \
    UA_TYPE_INIT_DEFAULT(TYPE)           \
    UA_TYPE_NEW_DEFAULT(TYPE)            \
    UA_TYPE_COPY_DEFAULT(TYPE)           \

#define UA_TYPE_NEW_DEFAULT(TYPE)                     \
    UA_Int32 TYPE##_new(TYPE **p) {                   \
		UA_Int32 retval = UA_SUCCESS;                 \
		retval |= UA_alloc((void **)p, sizeof(TYPE)); \
		retval |= TYPE##_init(*p);                    \
		return retval;                                \
	}

#define UA_TYPE_INIT_DEFAULT(TYPE)         \
    UA_Int32 TYPE##_init(TYPE * p) {       \
		if(p == UA_NULL) return UA_ERROR;  \
		*p = (TYPE)0;                      \
		return UA_SUCCESS;                 \
	}

#define UA_TYPE_INIT_AS(TYPE, TYPE_AS)       \
    UA_Int32 TYPE##_init(TYPE * p) {         \
		return TYPE_AS##_init((TYPE_AS *)p); \
	}

#define UA_TYPE_DELETE_DEFAULT(TYPE)       \
    UA_Int32 TYPE##_delete(TYPE *p) {      \
		UA_Int32 retval = UA_SUCCESS;      \
		retval |= TYPE##_deleteMembers(p); \
		retval |= UA_free(p);              \
		return retval;                     \
	}

#define UA_TYPE_DELETE_AS(TYPE, TYPE_AS) \
    UA_Int32 TYPE##_delete(TYPE * p) { return TYPE_AS##_delete((TYPE_AS *)p); }

#define UA_TYPE_DELETEMEMBERS_NOACTION(TYPE) \
    UA_Int32 TYPE##_deleteMembers(TYPE * p) { return UA_SUCCESS; }

#define UA_TYPE_DELETEMEMBERS_AS(TYPE, TYPE_AS) \
    UA_Int32 TYPE##_deleteMembers(TYPE * p) { return TYPE_AS##_deleteMembers((TYPE_AS *)p); }

/* Use only when the type has no arrays. Otherwise, implement deep copy */
#define UA_TYPE_COPY_DEFAULT(TYPE)                     \
    UA_Int32 TYPE##_copy(TYPE const *src, TYPE *dst) { \
		UA_Int32 retval = UA_SUCCESS;                  \
		retval |= UA_memcpy(dst, src, sizeof(TYPE));   \
		return retval;                                 \
	}

#define UA_TYPE_COPY_AS(TYPE, TYPE_AS)                         \
    UA_Int32 TYPE##_copy(TYPE const *src, TYPE *dst) {         \
		return TYPE_AS##_copy((TYPE_AS *)src, (TYPE_AS *)dst); \
	}

#define UA_TYPE_AS(TYPE, TYPE_AS)           \
    UA_TYPE_NEW_DEFAULT(TYPE)               \
    UA_TYPE_INIT_AS(TYPE, TYPE_AS)          \
    UA_TYPE_DELETE_AS(TYPE, TYPE_AS)        \
    UA_TYPE_DELETEMEMBERS_AS(TYPE, TYPE_AS) \
    UA_TYPE_COPY_AS(TYPE, TYPE_AS)

/// @} /* end of group */

#endif /* UA_TYPES_H_ */