types.h

Go to the documentation of this file.

/** This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 *    Copyright 2014 (c) Leon Urbas
 *    Copyright 2014, 2016-2017 (c) Florian Palm
 *    Copyright 2014-2017 (c) Fraunhofer IOSB (Author: Julius Pfrommer)
 *    Copyright 2015-2016 (c) Sten Grüner
 *    Copyright 2015-2016 (c) Chris Iatrou
 *    Copyright 2015 (c) Nick Goossens
 *    Copyright 2015-2016 (c) Oleksiy Vasylyev
 *    Copyright 2017 (c) Stefan Profanter, fortiss GmbH
 *    Copyright 2017 (c) Thomas Stalder, Blue Time Concept SA
 *    Copyright 2023 (c) Fraunhofer IOSB (Author: Andreas Ebner)
 */
 
#ifndef UA_TYPES_H_
#define UA_TYPES_H_
 
#include <open62541/config.h>
#include <open62541/common.h>
#include <open62541/statuscodes.h>
 
_UA_BEGIN_DECLS
 
 
typedef bool UA_Boolean;
#define UA_TRUE true UA_INTERNAL_DEPRECATED
#define UA_FALSE false UA_INTERNAL_DEPRECATED
 
 
typedef int8_t UA_SByte;
#define UA_SBYTE_MIN (-128)
#define UA_SBYTE_MAX 127
 
 
typedef uint8_t UA_Byte;
#define UA_BYTE_MIN 0
#define UA_BYTE_MAX 255
 
 
typedef int16_t UA_Int16;
#define UA_INT16_MIN (-32768)
#define UA_INT16_MAX 32767
 
 
typedef uint16_t UA_UInt16;
#define UA_UINT16_MIN 0
#define UA_UINT16_MAX 65535
 
 
typedef int32_t UA_Int32;
#define UA_INT32_MIN ((int32_t)-2147483648LL)
#define UA_INT32_MAX 2147483647L
 
 
typedef uint32_t UA_UInt32;
#define UA_UINT32_MIN 0
#define UA_UINT32_MAX 4294967295UL
 
 
typedef int64_t UA_Int64;
#define UA_INT64_MAX (int64_t)9223372036854775807LL
#define UA_INT64_MIN ((int64_t)-UA_INT64_MAX-1LL)
 
 
typedef uint64_t UA_UInt64;
#define UA_UINT64_MIN 0
#define UA_UINT64_MAX (uint64_t)18446744073709551615ULL
 
 
typedef float UA_Float;
#define UA_FLOAT_MIN FLT_MIN
#define UA_FLOAT_MAX FLT_MAX
 
 
typedef double UA_Double;
#define UA_DOUBLE_MIN DBL_MIN
#define UA_DOUBLE_MAX DBL_MAX
 
 
typedef uint32_t UA_StatusCode;
 
/** Returns the human-readable name of the StatusCode. If no matching StatusCode
 * is found, a default string for "Unknown" is returned. This feature might be
 * disabled to create a smaller binary with the
 * UA_ENABLE_STATUSCODE_DESCRIPTIONS build-flag. Then the function returns an
 * empty string for every StatusCode. */
UA_EXPORT const char *
UA_StatusCode_name(UA_StatusCode code);
 
/** Extracts the severity from a StatusCode. See Part 4, Section 7.34 for
 * details. */
UA_INLINABLE(UA_Boolean
             UA_StatusCode_isBad(UA_StatusCode code), {
    return ((code >> 30) >= 0x02);
})
 
UA_INLINABLE(UA_Boolean
             UA_StatusCode_isUncertain(UA_StatusCode code), {
    return ((code >> 30) == 0x01);
})
 
UA_INLINABLE(UA_Boolean
             UA_StatusCode_isGood(UA_StatusCode code), {
    return ((code >> 30) == 0x00);
})
 
/** Compares the top 16 bits of two StatusCodes for equality. This should only
 * be used when processing user-defined StatusCodes e.g when processing a ReadResponse.
 * As a convention, the lower bits of StatusCodes should not be used internally, meaning
 * can compare them without the use of this function. */
UA_INLINABLE(UA_Boolean
             UA_StatusCode_isEqualTop(UA_StatusCode s1, UA_StatusCode s2), {
    return ((s1 & 0xFFFF0000) == (s2 & 0xFFFF0000));
})
 
 
typedef struct {
    size_t length; /* The length of the string */
    UA_Byte *data; /* The content (not null-terminated) */
} UA_String;
 
/** Copies the content on the heap. Returns a null-string when alloc fails */
UA_String
UA_String_fromChars(const char *src);
 
UA_Boolean
UA_String_isEmpty(const UA_String *s);
 
UA_EXPORT extern const UA_String UA_STRING_NULL;
 
 
UA_INLINABLE(UA_String
             UA_STRING(char *chars), {
    UA_String s;
    memset(&s, 0, sizeof(s));
    if(!chars)
        return s;
    s.length = strlen(chars); s.data = (UA_Byte*)chars;
    return s;
})
 
#define UA_STRING_ALLOC(CHARS) UA_String_fromChars(CHARS)
 
/** Define strings at compile time (in ROM) */
#define UA_STRING_STATIC(CHARS) {sizeof(CHARS)-1, (UA_Byte*)CHARS}
 
 
 
typedef int64_t UA_DateTime;
 
/** Multiples to convert durations to DateTime */
#define UA_DATETIME_USEC 10LL
#define UA_DATETIME_MSEC (UA_DATETIME_USEC * 1000LL)
#define UA_DATETIME_SEC (UA_DATETIME_MSEC * 1000LL)
 
/** The current time in UTC time */
UA_DateTime UA_DateTime_now(void);
 
/** Offset between local time and UTC time */
UA_Int64 UA_DateTime_localTimeUtcOffset(void);
 
/** CPU clock invariant to system time changes. Use only to measure durations,
 * not absolute time. */
UA_DateTime UA_DateTime_nowMonotonic(void);
 
/** Represents a Datetime as a structure */
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;   /* From 1 to 31 */
    UA_UInt16 month; /* From 1 to 12 */
    UA_Int16 year;   /* Can be negative (BC) */
} UA_DateTimeStruct;
 
UA_DateTimeStruct UA_DateTime_toStruct(UA_DateTime t);
UA_DateTime UA_DateTime_fromStruct(UA_DateTimeStruct ts);
 
/** The C99 standard (7.23.1) says: "The range and precision of times
 * representable in clock_t and time_t are implementation-defined." On most
 * systems, time_t is a 4 or 8 byte integer counting seconds since the UTC Unix
 * epoch. The following methods are used for conversion. */
 
/** Datetime of 1 Jan 1970 00:00 */
#define UA_DATETIME_UNIX_EPOCH (11644473600LL * UA_DATETIME_SEC)
 
UA_INLINABLE(UA_Int64
             UA_DateTime_toUnixTime(UA_DateTime date), {
    return (date - UA_DATETIME_UNIX_EPOCH) / UA_DATETIME_SEC;
})
 
UA_INLINABLE(UA_DateTime
             UA_DateTime_fromUnixTime(UA_Int64 unixDate), {
    return (unixDate * UA_DATETIME_SEC) + UA_DATETIME_UNIX_EPOCH;
})
 
 
typedef struct {
    UA_UInt32 data1;
    UA_UInt16 data2;
    UA_UInt16 data3;
    UA_Byte   data4[8];
} UA_Guid;
 
UA_EXPORT extern const UA_Guid UA_GUID_NULL;
 
/** Print a Guid in the human-readable format defined in Part 6, 5.1.3
 *
 * Format: C496578A-0DFE-4B8F-870A-745238C6AEAE
 *         |       |    |    |    |            |
 *         0       8    13   18   23           36
 *
 * This allocates memory if the output argument is an empty string. Tries to use
 * the given buffer otherwise. */
UA_StatusCode
UA_Guid_print(const UA_Guid *guid, UA_String *output);
 
/** Parse the humand-readable Guid format */
#ifdef UA_ENABLE_PARSING
UA_StatusCode
UA_Guid_parse(UA_Guid *guid, const UA_String str);
 
UA_INLINABLE(UA_Guid
             UA_GUID(const char *chars), {
    UA_Guid guid;
    UA_Guid_parse(&guid, UA_STRING((char*)(uintptr_t)chars));
    return guid;
})
#endif
 
 
typedef UA_String UA_ByteString;
 
UA_EXPORT extern const UA_ByteString UA_BYTESTRING_NULL;
 
/** Allocates memory of size length for the bytestring.
 * The content is not set to zero. */
UA_StatusCode
UA_ByteString_allocBuffer(UA_ByteString *bs, size_t length);
 
/** Converts a ByteString to the corresponding
 * base64 representation */
UA_StatusCode
UA_ByteString_toBase64(const UA_ByteString *bs, UA_String *output);
 
/** Parse a ByteString from a base64 representation */
UA_StatusCode
UA_ByteString_fromBase64(UA_ByteString *bs,
                         const UA_String *input);
 
#define UA_BYTESTRING(chars) UA_STRING(chars)
#define UA_BYTESTRING_ALLOC(chars) UA_STRING_ALLOC(chars)
 
/** Returns a non-cryptographic hash of a bytestring */
UA_UInt32
UA_ByteString_hash(UA_UInt32 initialHashValue,
                   const UA_Byte *data, size_t size);
 
 
typedef UA_String UA_XmlElement;
 
 
enum UA_NodeIdType {
    UA_NODEIDTYPE_NUMERIC    = 0, /* In the binary encoding, this can also
                                   * become 1 or 2 (two-byte and four-byte
                                   * encoding of small 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;
 
UA_EXPORT extern const UA_NodeId UA_NODEID_NULL;
 
UA_Boolean UA_NodeId_isNull(const UA_NodeId *p);
 
/** Print the NodeId in the human-readable format defined in Part 6,
 * 5.3.1.10.
 *
 * Examples:
 *   UA_NODEID("i=13")
 *   UA_NODEID("ns=10;i=1")
 *   UA_NODEID("ns=10;s=Hello:World")
 *   UA_NODEID("g=09087e75-8e5e-499b-954f-f2a9603db28a")
 *   UA_NODEID("ns=1;b=b3BlbjYyNTQxIQ==") // base64
 *
 * The method can either use a pre-allocated string buffer or allocates memory
 * internally if called with an empty output string. */
UA_StatusCode
UA_NodeId_print(const UA_NodeId *id, UA_String *output);
 
/** Parse the human-readable NodeId format. Attention! String and
 * ByteString NodeIds have their identifier malloc'ed and need to be
 * cleaned up. */
#ifdef UA_ENABLE_PARSING
UA_StatusCode
UA_NodeId_parse(UA_NodeId *id, const UA_String str);
 
UA_INLINABLE(UA_NodeId
             UA_NODEID(const char *chars), {
    UA_NodeId id;
    UA_NodeId_parse(&id, UA_STRING((char*)(uintptr_t)chars));
    return id;
})
#endif
 
 
UA_INLINABLE(UA_NodeId
             UA_NODEID_NUMERIC(UA_UInt16 nsIndex,
                               UA_UInt32 identifier), {
    UA_NodeId id;
    memset(&id, 0, sizeof(UA_NodeId));
    id.namespaceIndex = nsIndex;
    id.identifierType = UA_NODEIDTYPE_NUMERIC;
    id.identifier.numeric = identifier;
    return id;
})
 
UA_INLINABLE(UA_NodeId
             UA_NODEID_STRING(UA_UInt16 nsIndex, char *chars), {
    UA_NodeId id;
    memset(&id, 0, sizeof(UA_NodeId));
    id.namespaceIndex = nsIndex;
    id.identifierType = UA_NODEIDTYPE_STRING;
    id.identifier.string = UA_STRING(chars);
    return id;
})
 
UA_INLINABLE(UA_NodeId
             UA_NODEID_STRING_ALLOC(UA_UInt16 nsIndex,
                                    const char *chars), {
    UA_NodeId id;
    memset(&id, 0, sizeof(UA_NodeId));
    id.namespaceIndex = nsIndex;
    id.identifierType = UA_NODEIDTYPE_STRING;
    id.identifier.string = UA_STRING_ALLOC(chars);
    return id;
})
 
UA_INLINABLE(UA_NodeId
             UA_NODEID_GUID(UA_UInt16 nsIndex, UA_Guid guid), {
    UA_NodeId id;
    memset(&id, 0, sizeof(UA_NodeId));
    id.namespaceIndex = nsIndex;
    id.identifierType = UA_NODEIDTYPE_GUID;
    id.identifier.guid = guid;
    return id;
})
 
UA_INLINABLE(UA_NodeId
             UA_NODEID_BYTESTRING(UA_UInt16 nsIndex, char *chars), {
    UA_NodeId id;
    memset(&id, 0, sizeof(UA_NodeId));
    id.namespaceIndex = nsIndex;
    id.identifierType = UA_NODEIDTYPE_BYTESTRING;
    id.identifier.byteString = UA_BYTESTRING(chars);
    return id;
})
 
UA_INLINABLE(UA_NodeId
             UA_NODEID_BYTESTRING_ALLOC(UA_UInt16 nsIndex,
                                        const char *chars), {
    UA_NodeId id;
    memset(&id, 0, sizeof(UA_NodeId));
    id.namespaceIndex = nsIndex;
    id.identifierType = UA_NODEIDTYPE_BYTESTRING;
    id.identifier.byteString = UA_BYTESTRING_ALLOC(chars);
    return id;
})
 
/** Total ordering of NodeId */
UA_Order
UA_NodeId_order(const UA_NodeId *n1, const UA_NodeId *n2);
 
/** Returns a non-cryptographic hash for NodeId */
UA_UInt32 UA_NodeId_hash(const UA_NodeId *n);
 
 
typedef struct {
    UA_NodeId nodeId;
    UA_String namespaceUri;
    UA_UInt32 serverIndex;
} UA_ExpandedNodeId;
 
UA_EXPORT extern const UA_ExpandedNodeId UA_EXPANDEDNODEID_NULL;
 
/** Print the ExpandedNodeId in the humand-readable format defined in Part 6,
 * 5.3.1.11:
 *
 *   svr=<serverindex>;ns=<namespaceindex>;<type>=<value>
 *     or
 *   svr=<serverindex>;nsu=<uri>;<type>=<value>
 *
 * The definitions for svr, ns and nsu is omitted if zero / the empty string.
 *
 * The method can either use a pre-allocated string buffer or allocates memory
 * internally if called with an empty output string. */
UA_StatusCode
UA_ExpandedNodeId_print(const UA_ExpandedNodeId *id, UA_String *output);
 
/** Parse the human-readable NodeId format. Attention! String and
 * ByteString NodeIds have their identifier malloc'ed and need to be
 * cleaned up. */
#ifdef UA_ENABLE_PARSING
UA_StatusCode
UA_ExpandedNodeId_parse(UA_ExpandedNodeId *id, const UA_String str);
 
UA_INLINABLE(UA_ExpandedNodeId
             UA_EXPANDEDNODEID(const char *chars), {
    UA_ExpandedNodeId id;
    UA_ExpandedNodeId_parse(&id, UA_STRING((char*)(uintptr_t)chars));
    return id;
})
#endif
 
 
UA_INLINABLE(UA_ExpandedNodeId
             UA_EXPANDEDNODEID_NUMERIC(UA_UInt16 nsIndex, UA_UInt32 identifier), {
    UA_ExpandedNodeId id; id.nodeId = UA_NODEID_NUMERIC(nsIndex, identifier);
    id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
})
 
UA_INLINABLE(UA_ExpandedNodeId
             UA_EXPANDEDNODEID_STRING(UA_UInt16 nsIndex, char *chars), {
    UA_ExpandedNodeId id; id.nodeId = UA_NODEID_STRING(nsIndex, chars);
    id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
})
 
UA_INLINABLE(UA_ExpandedNodeId
             UA_EXPANDEDNODEID_STRING_ALLOC(UA_UInt16 nsIndex, const char *chars), {
    UA_ExpandedNodeId id; id.nodeId = UA_NODEID_STRING_ALLOC(nsIndex, chars);
    id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
})
 
UA_INLINABLE(UA_ExpandedNodeId
             UA_EXPANDEDNODEID_STRING_GUID(UA_UInt16 nsIndex, UA_Guid guid), {
    UA_ExpandedNodeId id; id.nodeId = UA_NODEID_GUID(nsIndex, guid);
    id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
})
 
UA_INLINABLE(UA_ExpandedNodeId
             UA_EXPANDEDNODEID_BYTESTRING(UA_UInt16 nsIndex, char *chars), {
    UA_ExpandedNodeId id; id.nodeId = UA_NODEID_BYTESTRING(nsIndex, chars);
    id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
})
 
UA_INLINABLE(UA_ExpandedNodeId
             UA_EXPANDEDNODEID_BYTESTRING_ALLOC(UA_UInt16 nsIndex, const char *chars), {
    UA_ExpandedNodeId id; id.nodeId = UA_NODEID_BYTESTRING_ALLOC(nsIndex, chars);
    id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
})
 
UA_INLINABLE(UA_ExpandedNodeId
             UA_EXPANDEDNODEID_NODEID(UA_NodeId nodeId), {
    UA_ExpandedNodeId id; memset(&id, 0, sizeof(UA_ExpandedNodeId));
    id.nodeId = nodeId; return id;
})
 
/** Does the ExpandedNodeId point to a local node? That is, are namespaceUri and
 * serverIndex empty? */
UA_Boolean
UA_ExpandedNodeId_isLocal(const UA_ExpandedNodeId *n);
 
/** Total ordering of ExpandedNodeId */
UA_Order
UA_ExpandedNodeId_order(const UA_ExpandedNodeId *n1,
                        const UA_ExpandedNodeId *n2);
 
/** Returns a non-cryptographic hash for ExpandedNodeId. The hash of an
 * ExpandedNodeId is identical to the hash of the embedded (simple) NodeId if
 * the ServerIndex is zero and no NamespaceUri is set. */
UA_UInt32
UA_ExpandedNodeId_hash(const UA_ExpandedNodeId *n);
 
 
typedef struct {
    UA_UInt16 namespaceIndex;
    UA_String name;
} UA_QualifiedName;
 
UA_INLINABLE(UA_Boolean
             UA_QualifiedName_isNull(const UA_QualifiedName *q), {
    return (q->namespaceIndex == 0 && q->name.length == 0);
})
 
/** Returns a non-cryptographic hash for QualifiedName */
UA_UInt32
UA_QualifiedName_hash(const UA_QualifiedName *q);
 
UA_INLINABLE(UA_QualifiedName
             UA_QUALIFIEDNAME(UA_UInt16 nsIndex, char *chars), {
    UA_QualifiedName qn;
    qn.namespaceIndex = nsIndex;
    qn.name = UA_STRING(chars);
    return qn;
})
 
UA_INLINABLE(UA_QualifiedName
             UA_QUALIFIEDNAME_ALLOC(UA_UInt16 nsIndex, const char *chars), {
    UA_QualifiedName qn;
    qn.namespaceIndex = nsIndex;
    qn.name = UA_STRING_ALLOC(chars);
    return qn;
})
 
 
typedef struct {
    UA_String locale;
    UA_String text;
} UA_LocalizedText;
 
UA_INLINABLE(UA_LocalizedText
             UA_LOCALIZEDTEXT(char *locale, char *text), {
    UA_LocalizedText lt;
    lt.locale = UA_STRING(locale);
    lt.text = UA_STRING(text);
    return lt;
})
 
UA_INLINABLE(UA_LocalizedText
             UA_LOCALIZEDTEXT_ALLOC(const char *locale, const char *text), {
    UA_LocalizedText lt;
    lt.locale = UA_STRING_ALLOC(locale);
    lt.text = UA_STRING_ALLOC(text);
    return lt;
})
 
 
typedef struct {
    UA_UInt32 min;
    UA_UInt32 max;
} UA_NumericRangeDimension;
 
typedef struct  {
    size_t dimensionsSize;
    UA_NumericRangeDimension *dimensions;
} UA_NumericRange;
 
UA_StatusCode
UA_NumericRange_parse(UA_NumericRange *range, const UA_String str);
 
UA_INLINABLE(UA_NumericRange
             UA_NUMERICRANGE(const char *s), {
    UA_NumericRange nr;
    memset(&nr, 0, sizeof(nr)); 
    UA_NumericRange_parse(&nr, UA_STRING((char*)(uintptr_t)s));
    return nr;
})
 
 
/** Forward declaration. See the section on Generic Type Handling */
struct UA_DataType;
typedef struct UA_DataType UA_DataType;
 
#define UA_EMPTY_ARRAY_SENTINEL ((void*)0x01)
 
typedef 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 is
                              * not deleted when the variant is cleared up.
                              * The array dimensions also borrowed. */
} UA_VariantStorageType;
 
typedef struct {
    const UA_DataType *type;      /* The data type description */
    UA_VariantStorageType 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 */
    UA_UInt32 *arrayDimensions;   /* The length of each dimension */
} UA_Variant;
 
/** Returns true if the variant has no value defined (contains neither an array
 * nor a scalar value).
 *
 * @param v The variant
 * @return Is the variant empty */
UA_INLINABLE(UA_Boolean
             UA_Variant_isEmpty(const UA_Variant *v), {
    return v->type == NULL;
})
 
/** 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_INLINABLE(UA_Boolean
             UA_Variant_isScalar(const UA_Variant *v), {
    return (v->arrayLength == 0 && v->data > UA_EMPTY_ARRAY_SENTINEL);
})
 
/** Returns true if the variant contains a scalar value of the given type.
 *
 * @param v The variant
 * @param type The data type
 * @return Does the variant contain a scalar value of the given type */
UA_INLINABLE(UA_Boolean
             UA_Variant_hasScalarType(const UA_Variant *v,
                                      const UA_DataType *type), {
    return UA_Variant_isScalar(v) && type == v->type;
})
 
/** Returns true if the variant contains an array of the given type.
 *
 * @param v The variant
 * @param type The data type
 * @return Does the variant contain an array of the given type */
UA_INLINABLE(UA_Boolean
             UA_Variant_hasArrayType(const UA_Variant *v,
                                     const UA_DataType *type), {
    return (!UA_Variant_isScalar(v)) && type == v->type;
})
 
/** 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 */
void
UA_Variant_setScalar(UA_Variant *v, void *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 *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 cannot 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 *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);
 
 
typedef enum {
    UA_EXTENSIONOBJECT_ENCODED_NOBODY     = 0,
    UA_EXTENSIONOBJECT_ENCODED_BYTESTRING = 1,
    UA_EXTENSIONOBJECT_ENCODED_XML        = 2,
    UA_EXTENSIONOBJECT_DECODED            = 3,
    UA_EXTENSIONOBJECT_DECODED_NODELETE   = 4 /* Don't delete the content
                                                 together with the
                                                 ExtensionObject */
} UA_ExtensionObjectEncoding;
 
typedef struct {
    UA_ExtensionObjectEncoding 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;
 
/** Initialize the ExtensionObject and set the "decoded" value to the given
 * pointer. The value will be deleted when the ExtensionObject is cleared. */
void
UA_ExtensionObject_setValue(UA_ExtensionObject *eo,
                            void *p,
                            const UA_DataType *type);
 
/** Initialize the ExtensionObject and set the "decoded" value to the given
 * pointer. The value will *not* be deleted when the ExtensionObject is
 * cleared. */
void
UA_ExtensionObject_setValueNoDelete(UA_ExtensionObject *eo,
                                    void *p,
                                    const UA_DataType *type);
 
/** Initialize the ExtensionObject and set the "decoded" value to a fresh copy of
 * the given value pointer. The value will be deleted when the ExtensionObject
 * is cleared. */
UA_StatusCode
UA_ExtensionObject_setValueCopy(UA_ExtensionObject *eo,
                                void *p,
                                const UA_DataType *type);
 
 
typedef struct {
    UA_Variant    value;
    UA_DateTime   sourceTimestamp;
    UA_DateTime   serverTimestamp;
    UA_UInt16     sourcePicoseconds;
    UA_UInt16     serverPicoseconds;
    UA_StatusCode status;
    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_DataValue;
 
/** Copy the DataValue, but use only a subset of the (multidimensional) array of
 * of the variant of the source DataValue. Returns an error code if the variant
 * of the DataValue is not an array or if the indicated range does not fit.
 *
 * @param src The source DataValue
 * @param dst The target DataValue
 * @param range The range of the variant of the DataValue to copy
 * @return Returns UA_STATUSCODE_GOOD or an error code */
UA_StatusCode
UA_DataValue_copyVariantRange(const UA_DataValue *src, UA_DataValue *dst,
                              const UA_NumericRange range);
 
 
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;
 
 
 
typedef struct {
#ifdef UA_ENABLE_TYPEDESCRIPTION
    const char *memberName;       /* Human-readable member name */
#endif
    const UA_DataType *memberType;/* The member data type description */
    UA_Byte padding    : 6;       /* How much padding is there before this
                                     member element? For arrays this is the
                                     padding before the size_t length member.
                                     (No padding between size_t and the
                                     following ptr.) For unions, the padding
                                     includes the size of the switchfield (the
                                     offset from the start of the union
                                     type). */
    UA_Byte isArray    : 1;       /* The member is an array */
    UA_Byte isOptional : 1;       /* The member is an optional field */
} UA_DataTypeMember;
 
/** The DataType "kind" is an internal type classification. It is used to
 * dispatch handling to the correct routines. */
#define UA_DATATYPEKINDS 31
typedef enum {
    UA_DATATYPEKIND_BOOLEAN = 0,
    UA_DATATYPEKIND_SBYTE = 1,
    UA_DATATYPEKIND_BYTE = 2,
    UA_DATATYPEKIND_INT16 = 3,
    UA_DATATYPEKIND_UINT16 = 4,
    UA_DATATYPEKIND_INT32 = 5,
    UA_DATATYPEKIND_UINT32 = 6,
    UA_DATATYPEKIND_INT64 = 7,
    UA_DATATYPEKIND_UINT64 = 8,
    UA_DATATYPEKIND_FLOAT = 9,
    UA_DATATYPEKIND_DOUBLE = 10,
    UA_DATATYPEKIND_STRING = 11,
    UA_DATATYPEKIND_DATETIME = 12,
    UA_DATATYPEKIND_GUID = 13,
    UA_DATATYPEKIND_BYTESTRING = 14,
    UA_DATATYPEKIND_XMLELEMENT = 15,
    UA_DATATYPEKIND_NODEID = 16,
    UA_DATATYPEKIND_EXPANDEDNODEID = 17,
    UA_DATATYPEKIND_STATUSCODE = 18,
    UA_DATATYPEKIND_QUALIFIEDNAME = 19,
    UA_DATATYPEKIND_LOCALIZEDTEXT = 20,
    UA_DATATYPEKIND_EXTENSIONOBJECT = 21,
    UA_DATATYPEKIND_DATAVALUE = 22,
    UA_DATATYPEKIND_VARIANT = 23,
    UA_DATATYPEKIND_DIAGNOSTICINFO = 24,
    UA_DATATYPEKIND_DECIMAL = 25,
    UA_DATATYPEKIND_ENUM = 26,
    UA_DATATYPEKIND_STRUCTURE = 27,
    UA_DATATYPEKIND_OPTSTRUCT = 28, /* struct with optional fields */
    UA_DATATYPEKIND_UNION = 29,
    UA_DATATYPEKIND_BITFIELDCLUSTER = 30 /* bitfields + padding */
} UA_DataTypeKind;
 
struct UA_DataType {
#ifdef UA_ENABLE_TYPEDESCRIPTION
    const char *typeName;
#endif
    UA_NodeId typeId;           /* The nodeid of the type */
    UA_NodeId binaryEncodingId; /* NodeId of datatype when encoded as binary */
    //UA_NodeId xmlEncodingId;  /* NodeId of datatype when encoded as XML */
    UA_UInt32 memSize     : 16; /* Size of the struct in memory */
    UA_UInt32 typeKind    : 6;  /* Dispatch index for the handling routines */
    UA_UInt32 pointerFree : 1;  /* The type (and its members) contains no
                                 * pointers that need to be freed */
    UA_UInt32 overlayable : 1;  /* The type has the identical memory layout
                                 * in memory and on the binary stream. */
    UA_UInt32 membersSize : 8;  /* How many members does the type have? */
    UA_DataTypeMember *members;
};
 
/** Datatype arrays with custom type definitions can be added in a linked list to
 * the client or server configuration. */
typedef struct UA_DataTypeArray {
    const struct UA_DataTypeArray *next;
    const size_t typesSize;
    const UA_DataType *types;
    UA_Boolean cleanup; /* Free the array structure and its content
                           when the client or server configuration
                           containing it is cleaned up */
} UA_DataTypeArray;
 
/** Returns the offset and type of a structure member. The return value is false
 * if the member was not found.
 *
 * If the member is an array, the offset points to the (size_t) length field.
 * (The array pointer comes after the length field without any padding.) */
#ifdef UA_ENABLE_TYPEDESCRIPTION
UA_Boolean
UA_DataType_getStructMember(const UA_DataType *type,
                            const char *memberName,
                            size_t *outOffset,
                            const UA_DataType **outMemberType,
                            UA_Boolean *outIsArray);
#endif
 
/** Test if the data type is a numeric builtin data type (via the typeKind field
 * of UA_DataType). This includes integers and floating point numbers. Not
 * included are Boolean, DateTime, StatusCode and Enums. */
UA_Boolean
UA_DataType_isNumeric(const UA_DataType *type);
 
 
 
/** Returns the data type description for the type's identifier or NULL if no
 * matching data type was found. */
const UA_DataType *
UA_findDataType(const UA_NodeId *typeId);
 
/*
 * Add custom data types to the search scope of UA_findDataType. */
 
const UA_DataType *
UA_findDataTypeWithCustom(const UA_NodeId *typeId,
                          const UA_DataTypeArray *customTypes);
 
 
 
/** Allocates and initializes a variable of type dataType
 *
 * @param type The datatype description
 * @return Returns the memory location of the variable or NULL if no
 *         memory could be allocated */
void * UA_new(const UA_DataType *type);
 
/** Initializes a variable to default values
 *
 * @param p The memory location of the variable
 * @param type The datatype description */
UA_INLINABLE(void
             UA_init(void *p, const UA_DataType *type), {
    memset(p, 0, type->memSize);
})
 
/** Copies the content of two variables. If copying fails (e.g. because no memory
 * was available for an array), then dst is emptied and initialized to prevent
 * memory leaks.
 *
 * @param src The memory location of the source variable
 * @param dst The memory location of the destination variable
 * @param type The datatype description
 * @return Indicates whether the operation succeeded or returns an error code */
UA_StatusCode
UA_copy(const void *src, void *dst, const UA_DataType *type);
 
/** Deletes the dynamically allocated content of a variable (e.g. resets all
 * arrays to undefined arrays). Afterwards, the variable can be safely deleted
 * without causing memory leaks. But the variable is not initialized and may
 * contain old data that is not memory-relevant.
 *
 * @param p The memory location of the variable
 * @param type The datatype description of the variable */
void UA_clear(void *p, const UA_DataType *type);
 
#define UA_deleteMembers(p, type) UA_clear(p, type)
 
/** Frees a variable and all of its content.
 *
 * @param p The memory location of the variable
 * @param type The datatype description of the variable */
void UA_delete(void *p, const UA_DataType *type);
 
/** Pretty-print the value from the datatype. The output is pretty-printed JSON5.
 * Note that this format is non-standard and should not be sent over the
 * network. It can however be read by our own JSON decoding.
 *
 * @param p The memory location of the variable
 * @param type The datatype description of the variable
 * @param output A string that is used for the pretty-printed output. If the
 *        memory for string is already allocated, we try to use the existing
 *        string (the length is adjusted). If the string is empty, memory
 *        is allocated for it.
 * @return Indicates whether the operation succeeded */
#ifdef UA_ENABLE_JSON_ENCODING
UA_StatusCode
UA_print(const void *p, const UA_DataType *type, UA_String *output);
#endif
 
/** Compare two values and return their order.
 *
 * For numerical types (including StatusCodes and Enums), their natural order is
 * used. NaN is the "smallest" value for floating point values. Different bit
 * representations of NaN are considered identical.
 *
 * All other types have *some* absolute ordering so that a < b, b < c -> a < c.
 *
 * The ordering of arrays (also strings) is in "shortlex": A shorter array is
 * always smaller than a longer array. Otherwise the first different element
 * defines the order.
 *
 * When members of different types are permitted (in Variants and
 * ExtensionObjects), the memory address in the "UA_DataType*" pointer
 * determines which variable is smaller.
 *
 * @param p1 The memory location of the first value
 * @param p2 The memory location of the first value
 * @param type The datatype description of both values */
UA_Order
UA_order(const void *p1, const void *p2, const UA_DataType *type);
 
/** Compare if two values have identical content. */
UA_INLINABLE(UA_Boolean
             UA_equal(const void *p1, const void *p2, const UA_DataType *type), {
    return (UA_order(p1, p2, type) == UA_ORDER_EQ);
})
 
 
 
/** Returns the number of bytes the value p takes in binary encoding. Returns
 * zero if an error occurs. */
UA_EXPORT size_t
UA_calcSizeBinary(const void *p, const UA_DataType *type);
 
/** Encodes a data-structure in the binary format. If outBuf has a length of
 * zero, a buffer of the required size is allocated. Otherwise, encoding into
 * the existing outBuf is attempted (and may fail if the buffer is too
 * small). */
UA_EXPORT UA_StatusCode
UA_encodeBinary(const void *p, const UA_DataType *type,
                UA_ByteString *outBuf);
 
/** The structure with the decoding options may be extended in the future.
 * Zero-out the entire structure initially to ensure code-compatibility when
 * more fields are added in a later release. */
typedef struct {
    const UA_DataTypeArray *customTypes; /* Begin of a linked list with custom
                                          * datatype definitions */
} UA_DecodeBinaryOptions;
 
/** Decodes a data structure from the input buffer in the binary format. It is
 * assumed that `p` points to valid memory (not necessarily zeroed out). The
 * options can be NULL and will be disregarded in that case. */
UA_EXPORT UA_StatusCode
UA_decodeBinary(const UA_ByteString *inBuf,
                void *p, const UA_DataType *type,
                const UA_DecodeBinaryOptions *options);
 
 
 
#ifdef UA_ENABLE_JSON_ENCODING
 
typedef struct {
    const UA_String *namespaces;
    size_t namespacesSize;
    const UA_String *serverUris;
    size_t serverUrisSize;
    UA_Boolean useReversible;
 
    UA_Boolean prettyPrint;   /* Add newlines and spaces for legibility */
 
    /* Enabling the following options leads to non-standard compatible JSON5
     * encoding! Use it for pretty-printing, but not for sending messages over
     * the network. (Our own decoding can still parse it.) */
 
    UA_Boolean unquotedKeys;  /* Don't print quotes around object element keys */
    UA_Boolean stringNodeIds; /* String encoding for NodeIds, like "ns=1;i=42" */
} UA_EncodeJsonOptions;
 
/** Returns the number of bytes the value src takes in json encoding. Returns
 * zero if an error occurs. */
UA_EXPORT size_t
UA_calcSizeJson(const void *src, const UA_DataType *type,
                const UA_EncodeJsonOptions *options);
 
/** Encodes the scalar value described by type to json encoding.
 *
 * @param src The value. Must not be NULL.
 * @param type The value type. Must not be NULL.
 * @param outBuf Pointer to ByteString containing the result if the encoding
 *        was successful
 * @return Returns a statuscode whether encoding succeeded. */
UA_StatusCode
UA_encodeJson(const void *src, const UA_DataType *type, UA_ByteString *outBuf,
              const UA_EncodeJsonOptions *options);
 
/** The structure with the decoding options may be extended in the future.
 * Zero-out the entire structure initially to ensure code-compatibility when
 * more fields are added in a later release. */
typedef struct {
    const UA_String *namespaces;
    size_t namespacesSize;
    const UA_String *serverUris;
    size_t serverUrisSize;
    const UA_DataTypeArray *customTypes; /* Begin of a linked list with custom
                                          * datatype definitions */
} UA_DecodeJsonOptions;
 
/** Decodes a scalar value described by type from json encoding.
 *
 * @param src The buffer with the json encoded value. Must not be NULL.
 * @param dst The target value. Must not be NULL. The target is assumed to have
 *        size type->memSize. The value is reset to zero before decoding. If
 *        decoding fails, members are deleted and the value is reset (zeroed)
 *        again.
 * @param type The value type. Must not be NULL.
 * @param options The options struct for decoding, currently unused
 * @return Returns a statuscode whether decoding succeeded. */
UA_StatusCode
UA_decodeJson(const UA_ByteString *src, void *dst, const UA_DataType *type,
              const UA_DecodeJsonOptions *options);
 
#endif /* UA_ENABLE_JSON_ENCODING */
 
 
 
#ifdef UA_ENABLE_XML_ENCODING
 
typedef struct {
    UA_Boolean prettyPrint;   /* Add newlines and spaces for legibility */
} UA_EncodeXmlOptions;
 
/** Returns the number of bytes the value src takes in xml encoding. Returns
 * zero if an error occurs. */
UA_EXPORT size_t
UA_calcSizeXml(const void *src, const UA_DataType *type,
               const UA_EncodeXmlOptions *options);
 
/** Encodes the scalar value described by type to xml encoding.
 *
 * @param src The value. Must not be NULL.
 * @param type The value type. Must not be NULL.
 * @param outBuf Pointer to ByteString containing the result if the encoding
 *        was successful
 * @return Returns a statuscode whether encoding succeeded. */
UA_StatusCode
UA_encodeXml(const void *src, const UA_DataType *type, UA_ByteString *outBuf,
             const UA_EncodeXmlOptions *options);
 
/** The structure with the decoding options may be extended in the future.
 * Zero-out the entire structure initially to ensure code-compatibility when
 * more fields are added in a later release. */
typedef struct {
    const UA_DataTypeArray *customTypes; /* Begin of a linked list with custom
                                          * datatype definitions */
} UA_DecodeXmlOptions;
 
/** Decodes a scalar value described by type from xml encoding.
 *
 * @param src The buffer with the xml encoded value. Must not be NULL.
 * @param dst The target value. Must not be NULL. The target is assumed to have
 *        size type->memSize. The value is reset to zero before decoding. If
 *        decoding fails, members are deleted and the value is reset (zeroed)
 *        again.
 * @param type The value type. Must not be NULL.
 * @param options The options struct for decoding, currently unused
 * @return Returns a statuscode whether decoding succeeded. */
UA_StatusCode
UA_decodeXml(const UA_ByteString *src, void *dst, const UA_DataType *type,
             const UA_DecodeXmlOptions *options);
 
#endif /* UA_ENABLE_XML_ENCODING */
 
 
 
/** 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 NULL if no memory
 *         could be allocated */
void *
UA_Array_new(size_t size, const UA_DataType *type);
 
/** Allocates and copies an array
 *
 * @param src The memory location of the source array
 * @param 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 UA_STATUSCODE_GOOD or UA_STATUSCODE_BADOUTOFMEMORY */
UA_StatusCode
UA_Array_copy(const void *src, size_t size, void **dst,
              const UA_DataType *type);
 
/** Resizes (and reallocates) an array. The last entries are initialized to zero
 * if the array length is increased. If the array length is decreased, the last
 * entries are removed if the size is decreased.
 *
 * @param p Double pointer to the array memory. Can be overwritten by the result
 *          of a realloc.
 * @param size The current size of the array. Overwritten in case of success.
 * @param newSize The new size of the array
 * @param type The datatype of the array members
 * @return Returns UA_STATUSCODE_GOOD or UA_STATUSCODE_BADOUTOFMEMORY. The
 *         original array is left untouched in the failure case. */
UA_StatusCode
UA_Array_resize(void **p, size_t *size, size_t newSize,
                const UA_DataType *type);
 
/** Append the given element at the end of the array. The content is moved
 * (shallow copy) and the original memory is _init'ed if appending is
 * successful.
 *
 * @param p Double pointer to the array memory. Can be overwritten by the result
 *          of a realloc.
 * @param size The current size of the array. Overwritten in case of success.
 * @param newElem The element to be appended. The memory is reset upon success.
 * @param type The datatype of the array members
 * @return Returns UA_STATUSCODE_GOOD or UA_STATUSCODE_BADOUTOFMEMORY. The
 *         original array is left untouched in the failure case. */
UA_StatusCode
UA_Array_append(void **p, size_t *size, void *newElem,
                const UA_DataType *type);
 
/** Append a copy of the given element at the end of the array.
 *
 * @param p Double pointer to the array memory. Can be overwritten by the result
 *          of a realloc.
 * @param size The current size of the array. Overwritten in case of success.
 * @param newElem The element to be appended.
 * @param type The datatype of the array members
 * @return Returns UA_STATUSCODE_GOOD or UA_STATUSCODE_BADOUTOFMEMORY. The
 *         original array is left untouched in the failure case. */
 
UA_StatusCode
UA_Array_appendCopy(void **p, size_t *size, const void *newElem,
                    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);
 
 
 
/** stop-doc-generation */
 
/** Helper used to exclude type names in the definition of UA_DataType structures
 * if the feature is disabled. */
#ifdef UA_ENABLE_TYPEDESCRIPTION
# define UA_TYPENAME(name) name,
#else
# define UA_TYPENAME(name)
#endif
 
#include <open62541/types_generated.h>
#include <open62541/types_generated_handling.h>
 
_UA_END_DECLS
 
#endif /* UA_TYPES_H_ */