ua_types.h 31 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913
  1. /* Copyright (C) 2013-2016 the contributors as stated in the AUTHORS file
  2. *
  3. * This file is part of open62541. open62541 is free software: you can
  4. * redistribute it and/or modify it under the terms of the GNU Lesser General
  5. * Public License, version 3 (as published by the Free Software Foundation) with
  6. * a static linking exception as stated in the LICENSE file provided with
  7. * open62541.
  8. *
  9. * open62541 is distributed in the hope that it will be useful, but WITHOUT ANY
  10. * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  11. * A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
  12. * details. */
  13. #ifndef UA_TYPES_H_
  14. #define UA_TYPES_H_
  15. #ifdef __cplusplus
  16. extern "C" {
  17. #endif
  18. #include "ua_config.h"
  19. #include "ua_constants.h"
  20. /**
  21. * .. _types:
  22. *
  23. * Data Types
  24. * ==========
  25. *
  26. * The OPC UA protocol defines 25 builtin data types and three ways of combining
  27. * them into higher-order types: arrays, structures and unions. In open62541,
  28. * the builtin data types are defined manually. All other data types are
  29. * generated from standard XML definitions. Their exact definitions can be
  30. * looked up at https://opcfoundation.org/UA/schemas/Opc.Ua.Types.bsd.xml.
  31. *
  32. * Note that arrays can only be part of a scalar data type and never constitute
  33. * a data type on their own. Also, open62541 does not implement unions so far.
  34. * They are a recent addition to the protocol (since OPC UA v1.03). And so far,
  35. * no service definition makes of unions in the request / response message
  36. * definition. Instead, :ref:`Variants <variant>` are used when values of
  37. * different types are possible.
  38. *
  39. * All data types ``T`` (builtin and generated) share the same basic API for
  40. * creation, copying and deletion:
  41. *
  42. * - ``void T_init(T *ptr)``: Initialize the data type. This is synonymous with
  43. * zeroing out the memory, i.e. ``memset(ptr, 0, sizeof(T))``.
  44. * - ``T* T_new()``: Allocate and return the memory for the data type. The
  45. * value is already initialized.
  46. * - ``UA_StatusCode T_copy(const T *src, T *dst)``: Copy the content of the
  47. * data type. Returns ``UA_STATUSCODE_GOOD`` or
  48. * ``UA_STATUSCODE_BADOUTOFMEMORY``.
  49. * - ``void T_deleteMembers(T *ptr)``: Delete the dynamically allocated content
  50. * of the data type and perform a ``T_init`` to reset the type.
  51. * - ``void T_delete(T *ptr)``: Delete the content of the data type and the
  52. * memory for the data type itself. */
  53. #define UA_BUILTIN_TYPES_COUNT 25U
  54. /**
  55. * Builtin Types
  56. * -------------
  57. *
  58. * Boolean
  59. * ^^^^^^^
  60. * A two-state logical value (true or false). */
  61. typedef bool UA_Boolean;
  62. #define UA_TRUE true
  63. #define UA_FALSE false
  64. /**
  65. * SByte
  66. * ^^^^^
  67. * An integer value between -128 and 127. */
  68. typedef int8_t UA_SByte;
  69. #define UA_SBYTE_MIN (-128)
  70. #define UA_SBYTE_MAX 127
  71. /**
  72. * Byte
  73. * ^^^^
  74. * An integer value between 0 and 255. */
  75. typedef uint8_t UA_Byte;
  76. #define UA_BYTE_MIN 0
  77. #define UA_BYTE_MAX 255
  78. /**
  79. * Int16
  80. * ^^^^^
  81. * An integer value between -32 768 and 32 767. */
  82. typedef int16_t UA_Int16;
  83. #define UA_INT16_MIN (-32768)
  84. #define UA_INT16_MAX 32767
  85. /**
  86. * UInt16
  87. * ^^^^^^
  88. * An integer value between 0 and 65 535. */
  89. typedef uint16_t UA_UInt16;
  90. #define UA_UINT16_MIN 0
  91. #define UA_UINT16_MAX 65535
  92. /**
  93. * Int32
  94. * ^^^^^
  95. * An integer value between -2 147 483 648 and 2 147 483 647. */
  96. typedef int32_t UA_Int32;
  97. #define UA_INT32_MIN (-2147483648)
  98. #define UA_INT32_MAX 2147483647
  99. /**
  100. * UInt32
  101. * ^^^^^^
  102. * An integer value between 0 and 4 294 967 295. */
  103. typedef uint32_t UA_UInt32;
  104. #define UA_UINT32_MIN 0
  105. #define UA_UINT32_MAX 4294967295
  106. /**
  107. * Int64
  108. * ^^^^^
  109. * An integer value between -9 223 372 036 854 775 808 and
  110. * 9 223 372 036 854 775 807. */
  111. typedef int64_t UA_Int64;
  112. #define UA_INT64_MIN ((int64_t)-9223372036854775808)
  113. #define UA_INT64_MAX (int64_t)9223372036854775807
  114. /**
  115. * UInt64
  116. * ^^^^^^
  117. * An integer value between 0 and 18 446 744 073 709 551 615. */
  118. typedef uint64_t UA_UInt64;
  119. #define UA_UINT64_MIN (int64_t)0
  120. #define UA_UINT64_MAX (int64_t)18446744073709551615
  121. /**
  122. * Float
  123. * ^^^^^
  124. * An IEEE single precision (32 bit) floating point value. */
  125. typedef float UA_Float;
  126. /**
  127. * Double
  128. * ^^^^^^
  129. * An IEEE double precision (64 bit) floating point value. */
  130. typedef double UA_Double;
  131. /**
  132. * .. _statuscode:
  133. *
  134. * StatusCode
  135. * ^^^^^^^^^^
  136. * A numeric identifier for a error or condition that is associated with a value
  137. * or an operation. See the section :ref:`statuscodes` for the meaning of a
  138. * specific code. */
  139. typedef uint32_t UA_StatusCode;
  140. typedef struct {
  141. UA_StatusCode code; /* The numeric value of the StatusCode */
  142. const char* name; /* The symbolic name */
  143. const char* explanation; /* Short message explaining the StatusCode */
  144. } UA_StatusCodeDescription;
  145. /* Returns the description of the StatusCode. Never returns NULL, but a generic
  146. * description for invalid StatusCodes instead. */
  147. UA_EXPORT const UA_StatusCodeDescription *
  148. UA_StatusCode_description(UA_StatusCode code);
  149. static UA_INLINE const char *
  150. UA_StatusCode_name(UA_StatusCode code) {
  151. return UA_StatusCode_description(code)->name;
  152. }
  153. static UA_INLINE const char *
  154. UA_StatusCode_explanation(UA_StatusCode code) {
  155. return UA_StatusCode_description(code)->explanation;
  156. }
  157. /**
  158. * String
  159. * ^^^^^^
  160. * A sequence of Unicode characters. Strings are just an array of UA_Byte. */
  161. typedef struct {
  162. size_t length; /* The length of the string */
  163. UA_Byte *data; /* The content (not null-terminated) */
  164. } UA_String;
  165. /* Copies the content on the heap. Returns a null-string when alloc fails */
  166. UA_String UA_EXPORT UA_String_fromChars(char const src[]) UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  167. UA_Boolean UA_EXPORT UA_String_equal(const UA_String *s1, const UA_String *s2);
  168. UA_EXPORT extern const UA_String UA_STRING_NULL;
  169. /**
  170. * ``UA_STRING`` returns a string pointing to the preallocated char-array.
  171. * ``UA_STRING_ALLOC`` is shorthand for ``UA_String_fromChars`` and makes a copy
  172. * of the char-array. */
  173. static UA_INLINE UA_String
  174. UA_STRING(char *chars) {
  175. UA_String str; str.length = strlen(chars);
  176. str.data = (UA_Byte*)chars; return str;
  177. }
  178. #define UA_STRING_ALLOC(CHARS) UA_String_fromChars(CHARS)
  179. /**
  180. * DateTime
  181. * ^^^^^^^^
  182. * An instance in time. A DateTime value is encoded as a 64-bit signed integer
  183. * which represents the number of 100 nanosecond intervals since January 1, 1601
  184. * (UTC). */
  185. typedef int64_t UA_DateTime;
  186. /* Multiply to convert units for time difference computations */
  187. #define UA_USEC_TO_DATETIME 10LL
  188. #define UA_MSEC_TO_DATETIME (UA_USEC_TO_DATETIME * 1000LL)
  189. #define UA_SEC_TO_DATETIME (UA_MSEC_TO_DATETIME * 1000LL)
  190. /* Datetime of 1 Jan 1970 00:00 UTC */
  191. #define UA_DATETIME_UNIX_EPOCH (11644473600LL * UA_SEC_TO_DATETIME)
  192. /* The current time */
  193. UA_DateTime UA_EXPORT UA_DateTime_now(void);
  194. /* CPU clock invariant to system time changes. Use only for time diffs, not
  195. * current time */
  196. UA_DateTime UA_EXPORT UA_DateTime_nowMonotonic(void);
  197. typedef struct UA_DateTimeStruct {
  198. UA_UInt16 nanoSec;
  199. UA_UInt16 microSec;
  200. UA_UInt16 milliSec;
  201. UA_UInt16 sec;
  202. UA_UInt16 min;
  203. UA_UInt16 hour;
  204. UA_UInt16 day;
  205. UA_UInt16 month;
  206. UA_UInt16 year;
  207. } UA_DateTimeStruct;
  208. UA_DateTimeStruct UA_EXPORT UA_DateTime_toStruct(UA_DateTime t);
  209. UA_String UA_EXPORT UA_DateTime_toString(UA_DateTime t);
  210. /**
  211. * Guid
  212. * ^^^^
  213. * A 16 byte value that can be used as a globally unique identifier. */
  214. typedef struct {
  215. UA_UInt32 data1;
  216. UA_UInt16 data2;
  217. UA_UInt16 data3;
  218. UA_Byte data4[8];
  219. } UA_Guid;
  220. UA_Boolean UA_EXPORT UA_Guid_equal(const UA_Guid *g1, const UA_Guid *g2);
  221. UA_EXPORT extern const UA_Guid UA_GUID_NULL;
  222. /**
  223. * ByteString
  224. * ^^^^^^^^^^
  225. * A sequence of octets. */
  226. typedef UA_String UA_ByteString;
  227. static UA_INLINE UA_Boolean
  228. UA_ByteString_equal(const UA_ByteString *string1, const UA_ByteString *string2) {
  229. return UA_String_equal((const UA_String*)string1, (const UA_String*)string2);
  230. }
  231. /* Allocates memory of size length for the bytestring.
  232. * The content is not set to zero. */
  233. UA_StatusCode UA_EXPORT
  234. UA_ByteString_allocBuffer(UA_ByteString *bs, size_t length);
  235. UA_EXPORT extern const UA_ByteString UA_BYTESTRING_NULL;
  236. static UA_INLINE UA_ByteString
  237. UA_BYTESTRING(char *chars) {
  238. UA_ByteString str; str.length = strlen(chars);
  239. str.data = (UA_Byte*)chars; return str;
  240. }
  241. static UA_INLINE UA_ByteString
  242. UA_BYTESTRING_ALLOC(const char *chars) {
  243. UA_String str = UA_String_fromChars(chars); UA_ByteString bstr;
  244. bstr.length = str.length; bstr.data = str.data; return bstr;
  245. }
  246. /**
  247. * XmlElement
  248. * ^^^^^^^^^^
  249. * An XML element. */
  250. typedef UA_String UA_XmlElement;
  251. /**
  252. * .. _nodeid:
  253. *
  254. * NodeId
  255. * ^^^^^^
  256. * An identifier for a node in the address space of an OPC UA Server. */
  257. enum UA_NodeIdType {
  258. UA_NODEIDTYPE_NUMERIC = 0, /* In the binary encoding, this can also
  259. become 1 or 2 (2byte and 4byte encoding of
  260. small numeric nodeids) */
  261. UA_NODEIDTYPE_STRING = 3,
  262. UA_NODEIDTYPE_GUID = 4,
  263. UA_NODEIDTYPE_BYTESTRING = 5
  264. };
  265. typedef struct {
  266. UA_UInt16 namespaceIndex;
  267. enum UA_NodeIdType identifierType;
  268. union {
  269. UA_UInt32 numeric;
  270. UA_String string;
  271. UA_Guid guid;
  272. UA_ByteString byteString;
  273. } identifier;
  274. } UA_NodeId;
  275. UA_EXPORT extern const UA_NodeId UA_NODEID_NULL;
  276. UA_Boolean UA_EXPORT UA_NodeId_isNull(const UA_NodeId *p);
  277. UA_Boolean UA_EXPORT UA_NodeId_equal(const UA_NodeId *n1, const UA_NodeId *n2);
  278. /* Returns a non-cryptographic hash for the NodeId */
  279. UA_UInt32 UA_EXPORT UA_NodeId_hash(const UA_NodeId *n);
  280. /** The following functions are shorthand for creating NodeIds. */
  281. static UA_INLINE UA_NodeId
  282. UA_NODEID_NUMERIC(UA_UInt16 nsIndex, UA_UInt32 identifier) {
  283. UA_NodeId id; id.namespaceIndex = nsIndex;
  284. id.identifierType = UA_NODEIDTYPE_NUMERIC;
  285. id.identifier.numeric = identifier; return id;
  286. }
  287. static UA_INLINE UA_NodeId
  288. UA_NODEID_STRING(UA_UInt16 nsIndex, char *chars) {
  289. UA_NodeId id; id.namespaceIndex = nsIndex;
  290. id.identifierType = UA_NODEIDTYPE_STRING;
  291. id.identifier.string = UA_STRING(chars); return id;
  292. }
  293. static UA_INLINE UA_NodeId
  294. UA_NODEID_STRING_ALLOC(UA_UInt16 nsIndex, const char *chars) {
  295. UA_NodeId id; id.namespaceIndex = nsIndex;
  296. id.identifierType = UA_NODEIDTYPE_STRING;
  297. id.identifier.string = UA_STRING_ALLOC(chars); return id;
  298. }
  299. static UA_INLINE UA_NodeId
  300. UA_NODEID_GUID(UA_UInt16 nsIndex, UA_Guid guid) {
  301. UA_NodeId id; id.namespaceIndex = nsIndex;
  302. id.identifierType = UA_NODEIDTYPE_GUID;
  303. id.identifier.guid = guid; return id;
  304. }
  305. static UA_INLINE UA_NodeId
  306. UA_NODEID_BYTESTRING(UA_UInt16 nsIndex, char *chars) {
  307. UA_NodeId id; id.namespaceIndex = nsIndex;
  308. id.identifierType = UA_NODEIDTYPE_BYTESTRING;
  309. id.identifier.byteString = UA_BYTESTRING(chars); return id;
  310. }
  311. static UA_INLINE UA_NodeId
  312. UA_NODEID_BYTESTRING_ALLOC(UA_UInt16 nsIndex, const char *chars) {
  313. UA_NodeId id; id.namespaceIndex = nsIndex;
  314. id.identifierType = UA_NODEIDTYPE_BYTESTRING;
  315. id.identifier.byteString = UA_BYTESTRING_ALLOC(chars); return id;
  316. }
  317. /**
  318. * ExpandedNodeId
  319. * ^^^^^^^^^^^^^^
  320. * A NodeId that allows the namespace URI to be specified instead of an index. */
  321. typedef struct {
  322. UA_NodeId nodeId;
  323. UA_String namespaceUri;
  324. UA_UInt32 serverIndex;
  325. } UA_ExpandedNodeId;
  326. /** The following functions are shorthand for creating ExpandedNodeIds. */
  327. static UA_INLINE UA_ExpandedNodeId
  328. UA_EXPANDEDNODEID_NUMERIC(UA_UInt16 nsIndex, UA_UInt32 identifier) {
  329. UA_ExpandedNodeId id; id.nodeId = UA_NODEID_NUMERIC(nsIndex, identifier);
  330. id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
  331. }
  332. static UA_INLINE UA_ExpandedNodeId
  333. UA_EXPANDEDNODEID_STRING(UA_UInt16 nsIndex, char *chars) {
  334. UA_ExpandedNodeId id; id.nodeId = UA_NODEID_STRING(nsIndex, chars);
  335. id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
  336. }
  337. static UA_INLINE UA_ExpandedNodeId
  338. UA_EXPANDEDNODEID_STRING_ALLOC(UA_UInt16 nsIndex, const char *chars) {
  339. UA_ExpandedNodeId id; id.nodeId = UA_NODEID_STRING_ALLOC(nsIndex, chars);
  340. id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
  341. }
  342. static UA_INLINE UA_ExpandedNodeId
  343. UA_EXPANDEDNODEID_STRING_GUID(UA_UInt16 nsIndex, UA_Guid guid) {
  344. UA_ExpandedNodeId id; id.nodeId = UA_NODEID_GUID(nsIndex, guid);
  345. id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
  346. }
  347. static UA_INLINE UA_ExpandedNodeId
  348. UA_EXPANDEDNODEID_BYTESTRING(UA_UInt16 nsIndex, char *chars) {
  349. UA_ExpandedNodeId id; id.nodeId = UA_NODEID_BYTESTRING(nsIndex, chars);
  350. id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
  351. }
  352. static UA_INLINE UA_ExpandedNodeId
  353. UA_EXPANDEDNODEID_BYTESTRING_ALLOC(UA_UInt16 nsIndex, const char *chars) {
  354. UA_ExpandedNodeId id; id.nodeId = UA_NODEID_BYTESTRING_ALLOC(nsIndex, chars);
  355. id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
  356. }
  357. /**
  358. * .. _qualifiedname:
  359. *
  360. * QualifiedName
  361. * ^^^^^^^^^^^^^
  362. * A name qualified by a namespace. */
  363. typedef struct {
  364. UA_UInt16 namespaceIndex;
  365. UA_String name;
  366. } UA_QualifiedName;
  367. static UA_INLINE UA_Boolean
  368. UA_QualifiedName_isNull(const UA_QualifiedName *q) {
  369. return (q->namespaceIndex == 0 && q->name.length == 0);
  370. }
  371. static UA_INLINE UA_QualifiedName
  372. UA_QUALIFIEDNAME(UA_UInt16 nsIndex, char *chars) {
  373. UA_QualifiedName qn; qn.namespaceIndex = nsIndex;
  374. qn.name = UA_STRING(chars); return qn;
  375. }
  376. static UA_INLINE UA_QualifiedName
  377. UA_QUALIFIEDNAME_ALLOC(UA_UInt16 nsIndex, const char *chars) {
  378. UA_QualifiedName qn; qn.namespaceIndex = nsIndex;
  379. qn.name = UA_STRING_ALLOC(chars); return qn;
  380. }
  381. /**
  382. * LocalizedText
  383. * ^^^^^^^^^^^^^
  384. * Human readable text with an optional locale identifier. */
  385. typedef struct {
  386. UA_String locale;
  387. UA_String text;
  388. } UA_LocalizedText;
  389. static UA_INLINE UA_LocalizedText
  390. UA_LOCALIZEDTEXT(char *locale, char *text) {
  391. UA_LocalizedText lt; lt.locale = UA_STRING(locale);
  392. lt.text = UA_STRING(text); return lt;
  393. }
  394. static UA_INLINE UA_LocalizedText
  395. UA_LOCALIZEDTEXT_ALLOC(const char *locale, const char *text) {
  396. UA_LocalizedText lt; lt.locale = UA_STRING_ALLOC(locale);
  397. lt.text = UA_STRING_ALLOC(text); return lt;
  398. }
  399. /**
  400. * .. _variant:
  401. *
  402. * Variant
  403. * ^^^^^^^
  404. *
  405. * Variants may contain values of any type together with a description of the
  406. * content. See the section on :ref:`generic-types` on how types are described.
  407. * The standard mandates that variants contain built-in data types only. If the
  408. * value is not of a builtin type, it is wrapped into an :ref:`extensionobject`.
  409. * open62541 hides this wrapping transparently in the encoding layer. If the
  410. * data type is unknown to the receiver, the variant contains the original
  411. * ExtensionObject in binary or XML encoding.
  412. *
  413. * Variants may contain a scalar value or an array. For details on the handling
  414. * of arrays, see the section on :ref:`array-handling`. Array variants can have
  415. * an additional dimensionality (matrix, 3-tensor, ...) defined in an array of
  416. * dimension lengths. The actual values are kept in an array of dimensions one.
  417. * For users who work with higher-dimensions arrays directly, keep in mind that
  418. * dimensions of higher rank are serialized first (the highest rank dimension
  419. * has stride 1 and elements follow each other directly). Usually it is simplest
  420. * to interact with higher-dimensional arrays via ``UA_NumericRange``
  421. * descriptions (see :ref:`array-handling`).
  422. *
  423. * To differentiate between scalar / array variants, the following definition is
  424. * used. ``UA_Variant_isScalar`` provides simplified access to these checks.
  425. *
  426. * - ``arrayLength == 0 && data == NULL``: undefined array of length -1
  427. * - ``arrayLength == 0 && data == UA_EMPTY_ARRAY_SENTINEL``: array of length 0
  428. * - ``arrayLength == 0 && data > UA_EMPTY_ARRAY_SENTINEL``: scalar value
  429. * - ``arrayLength > 0``: array of the given length
  430. *
  431. * Variants can also be *empty*. Then, the pointer to the type description is
  432. * ``NULL``. */
  433. /* Forward declaration. See the section on Generic Type Handling */
  434. struct UA_DataType;
  435. typedef struct UA_DataType UA_DataType;
  436. /* Forward declaration. See the section on Array Handling */
  437. struct UA_NumericRange;
  438. typedef struct UA_NumericRange UA_NumericRange;
  439. #define UA_EMPTY_ARRAY_SENTINEL ((void*)0x01)
  440. typedef enum {
  441. UA_VARIANT_DATA, /* The data has the same lifecycle as the
  442. variant */
  443. UA_VARIANT_DATA_NODELETE, /* The data is "borrowed" by the variant and
  444. shall not be deleted at the end of the
  445. variant's lifecycle. */
  446. } UA_VariantStorageType;
  447. typedef struct {
  448. const UA_DataType *type; /* The data type description */
  449. UA_VariantStorageType storageType;
  450. size_t arrayLength; /* The number of elements in the data array */
  451. void *data; /* Points to the scalar or array data */
  452. size_t arrayDimensionsSize; /* The number of dimensions */
  453. UA_UInt32 *arrayDimensions; /* The length of each dimension */
  454. } UA_Variant;
  455. /* Returns true if the variant has no value defined (contains neither an array
  456. * nor a scalar value).
  457. *
  458. * @param v The variant
  459. * @return Is the variant empty */
  460. static UA_INLINE UA_Boolean
  461. UA_Variant_isEmpty(const UA_Variant *v) {
  462. return v->type == NULL;
  463. }
  464. /* Returns true if the variant contains a scalar value. Note that empty variants
  465. * contain an array of length -1 (undefined).
  466. *
  467. * @param v The variant
  468. * @return Does the variant contain a scalar value */
  469. static UA_INLINE UA_Boolean
  470. UA_Variant_isScalar(const UA_Variant *v) {
  471. return (v->arrayLength == 0 && v->data > UA_EMPTY_ARRAY_SENTINEL);
  472. }
  473. /* Returns true if the variant contains a scalar value of the given type.
  474. *
  475. * @param v The variant
  476. * @param type The data type
  477. * @return Does the variant contain a scalar value of the given type */
  478. static UA_INLINE UA_Boolean
  479. UA_Variant_hasScalarType(const UA_Variant *v, const UA_DataType *type) {
  480. return UA_Variant_isScalar(v) && type == v->type;
  481. }
  482. /* Returns true if the variant contains an array of the given type.
  483. *
  484. * @param v The variant
  485. * @param type The data type
  486. * @return Does the variant contain an array of the given type */
  487. static UA_INLINE UA_Boolean
  488. UA_Variant_hasArrayType(const UA_Variant *v, const UA_DataType *type) {
  489. return (!UA_Variant_isScalar(v)) && type == v->type;
  490. }
  491. /* Set the variant to a scalar value that already resides in memory. The value
  492. * takes on the lifecycle of the variant and is deleted with it.
  493. *
  494. * @param v The variant
  495. * @param p A pointer to the value data
  496. * @param type The datatype of the value in question */
  497. void UA_EXPORT
  498. UA_Variant_setScalar(UA_Variant *v, void * UA_RESTRICT p,
  499. const UA_DataType *type);
  500. /* Set the variant to a scalar value that is copied from an existing variable.
  501. * @param v The variant
  502. * @param p A pointer to the value data
  503. * @param type The datatype of the value
  504. * @return Indicates whether the operation succeeded or returns an error code */
  505. UA_StatusCode UA_EXPORT
  506. UA_Variant_setScalarCopy(UA_Variant *v, const void *p,
  507. const UA_DataType *type);
  508. /* Set the variant to an array that already resides in memory. The array takes
  509. * on the lifecycle of the variant and is deleted with it.
  510. *
  511. * @param v The variant
  512. * @param array A pointer to the array data
  513. * @param arraySize The size of the array
  514. * @param type The datatype of the array */
  515. void UA_EXPORT
  516. UA_Variant_setArray(UA_Variant *v, void * UA_RESTRICT array,
  517. size_t arraySize, const UA_DataType *type);
  518. /* Set the variant to an array that is copied from an existing array.
  519. *
  520. * @param v The variant
  521. * @param array A pointer to the array data
  522. * @param arraySize The size of the array
  523. * @param type The datatype of the array
  524. * @return Indicates whether the operation succeeded or returns an error code */
  525. UA_StatusCode UA_EXPORT
  526. UA_Variant_setArrayCopy(UA_Variant *v, const void *array,
  527. size_t arraySize, const UA_DataType *type);
  528. /* Copy the variant, but use only a subset of the (multidimensional) array into
  529. * a variant. Returns an error code if the variant is not an array or if the
  530. * indicated range does not fit.
  531. *
  532. * @param src The source variant
  533. * @param dst The target variant
  534. * @param range The range of the copied data
  535. * @return Returns UA_STATUSCODE_GOOD or an error code */
  536. UA_StatusCode UA_EXPORT
  537. UA_Variant_copyRange(const UA_Variant *src, UA_Variant *dst,
  538. const UA_NumericRange range);
  539. /* Insert a range of data into an existing variant. The data array can't be
  540. * reused afterwards if it contains types without a fixed size (e.g. strings)
  541. * since the members are moved into the variant and take on its lifecycle.
  542. *
  543. * @param v The variant
  544. * @param dataArray The data array. The type must match the variant
  545. * @param dataArraySize The length of the data array. This is checked to match
  546. * the range size.
  547. * @param range The range of where the new data is inserted
  548. * @return Returns UA_STATUSCODE_GOOD or an error code */
  549. UA_StatusCode UA_EXPORT
  550. UA_Variant_setRange(UA_Variant *v, void * UA_RESTRICT array,
  551. size_t arraySize, const UA_NumericRange range);
  552. /* Deep-copy a range of data into an existing variant.
  553. *
  554. * @param v The variant
  555. * @param dataArray The data array. The type must match the variant
  556. * @param dataArraySize The length of the data array. This is checked to match
  557. * the range size.
  558. * @param range The range of where the new data is inserted
  559. * @return Returns UA_STATUSCODE_GOOD or an error code */
  560. UA_StatusCode UA_EXPORT
  561. UA_Variant_setRangeCopy(UA_Variant *v, const void *array,
  562. size_t arraySize, const UA_NumericRange range);
  563. /**
  564. * .. _extensionobject:
  565. *
  566. * ExtensionObject
  567. * ^^^^^^^^^^^^^^^
  568. *
  569. * ExtensionObjects may contain scalars of any data type. Even those that are
  570. * unknown to the receiver. See the section on :ref:`generic-types` on how types
  571. * are described. If the received data type is unkown, the encoded string and
  572. * target NodeId is stored instead of the decoded value. */
  573. typedef enum {
  574. UA_EXTENSIONOBJECT_ENCODED_NOBODY = 0,
  575. UA_EXTENSIONOBJECT_ENCODED_BYTESTRING = 1,
  576. UA_EXTENSIONOBJECT_ENCODED_XML = 2,
  577. UA_EXTENSIONOBJECT_DECODED = 3,
  578. UA_EXTENSIONOBJECT_DECODED_NODELETE = 4 /* Don't delete the content
  579. together with the
  580. ExtensionObject */
  581. } UA_ExtensionObjectEncoding;
  582. typedef struct {
  583. UA_ExtensionObjectEncoding encoding;
  584. union {
  585. struct {
  586. UA_NodeId typeId; /* The nodeid of the datatype */
  587. UA_ByteString body; /* The bytestring of the encoded data */
  588. } encoded;
  589. struct {
  590. const UA_DataType *type;
  591. void *data;
  592. } decoded;
  593. } content;
  594. } UA_ExtensionObject;
  595. /**
  596. * .. _datavalue:
  597. *
  598. * DataValue
  599. * ^^^^^^^^^
  600. * A data value with an associated status code and timestamps. */
  601. typedef struct {
  602. UA_Boolean hasValue : 1;
  603. UA_Boolean hasStatus : 1;
  604. UA_Boolean hasSourceTimestamp : 1;
  605. UA_Boolean hasServerTimestamp : 1;
  606. UA_Boolean hasSourcePicoseconds : 1;
  607. UA_Boolean hasServerPicoseconds : 1;
  608. UA_Variant value;
  609. UA_StatusCode status;
  610. UA_DateTime sourceTimestamp;
  611. UA_UInt16 sourcePicoseconds;
  612. UA_DateTime serverTimestamp;
  613. UA_UInt16 serverPicoseconds;
  614. } UA_DataValue;
  615. /**
  616. * DiagnosticInfo
  617. * ^^^^^^^^^^^^^^
  618. * A structure that contains detailed error and diagnostic information
  619. * associated with a StatusCode. */
  620. typedef struct UA_DiagnosticInfo {
  621. UA_Boolean hasSymbolicId : 1;
  622. UA_Boolean hasNamespaceUri : 1;
  623. UA_Boolean hasLocalizedText : 1;
  624. UA_Boolean hasLocale : 1;
  625. UA_Boolean hasAdditionalInfo : 1;
  626. UA_Boolean hasInnerStatusCode : 1;
  627. UA_Boolean hasInnerDiagnosticInfo : 1;
  628. UA_Int32 symbolicId;
  629. UA_Int32 namespaceUri;
  630. UA_Int32 localizedText;
  631. UA_Int32 locale;
  632. UA_String additionalInfo;
  633. UA_StatusCode innerStatusCode;
  634. struct UA_DiagnosticInfo *innerDiagnosticInfo;
  635. } UA_DiagnosticInfo;
  636. /**
  637. * .. _generic-types:
  638. *
  639. * Generic Type Handling
  640. * ---------------------
  641. * The builtin types can be combined to data structures. All information about a
  642. * (structured) data type is stored in a ``UA_DataType``. The array ``UA_TYPES``
  643. * contains the description of all standard-defined types and is used for
  644. * handling of generic types. */
  645. typedef struct {
  646. #ifdef UA_ENABLE_TYPENAMES
  647. const char *memberName;
  648. #endif
  649. UA_UInt16 memberTypeIndex; /* Index of the member in the array of data
  650. types */
  651. UA_Byte padding; /* How much padding is there before this
  652. member element? For arrays this is the
  653. padding before the size_t lenght member.
  654. (No padding between size_t and the
  655. following ptr.) */
  656. UA_Boolean namespaceZero : 1; /* The type of the member is defined in
  657. namespace zero. In this implementation,
  658. types from custom namespace may contain
  659. members from the same namespace or
  660. namespace zero only.*/
  661. UA_Boolean isArray : 1; /* The member is an array */
  662. } UA_DataTypeMember;
  663. struct UA_DataType {
  664. #ifdef UA_ENABLE_TYPENAMES
  665. const char *typeName;
  666. #endif
  667. UA_NodeId typeId; /* The nodeid of the type */
  668. UA_UInt16 memSize; /* Size of the struct in memory */
  669. UA_UInt16 typeIndex; /* Index of the type in the datatypetable */
  670. UA_Byte membersSize; /* How many members does the type have? */
  671. UA_Boolean builtin : 1; /* The type is "builtin" and has dedicated de-
  672. and encoding functions */
  673. UA_Boolean fixedSize : 1; /* The type (and its members) contains no
  674. pointers */
  675. UA_Boolean overlayable : 1; /* The type has the identical memory layout in
  676. memory and on the binary stream. */
  677. UA_UInt16 binaryEncodingId; /* NodeId of datatype when encoded as binary */
  678. //UA_UInt16 xmlEncodingId; /* NodeId of datatype when encoded as XML */
  679. UA_DataTypeMember *members;
  680. };
  681. /**
  682. * Builtin data types can be accessed as UA_TYPES[UA_TYPES_XXX], where XXX is
  683. * the name of the data type. If only the NodeId of a type is known, use the
  684. * following method to retrieve the data type description. */
  685. /* Returns the data type description for the type's identifier or NULL if no
  686. * matching data type was found. */
  687. const UA_DataType UA_EXPORT *
  688. UA_findDataType(const UA_NodeId *typeId);
  689. /** The following functions are used for generic handling of data types. */
  690. /* Allocates and initializes a variable of type dataType
  691. *
  692. * @param type The datatype description
  693. * @return Returns the memory location of the variable or NULL if no
  694. * memory could be allocated */
  695. void UA_EXPORT * UA_new(const UA_DataType *type) UA_FUNC_ATTR_MALLOC;
  696. /* Initializes a variable to default values
  697. *
  698. * @param p The memory location of the variable
  699. * @param type The datatype description */
  700. static UA_INLINE void
  701. UA_init(void *p, const UA_DataType *type) {
  702. memset(p, 0, type->memSize);
  703. }
  704. /* Copies the content of two variables. If copying fails (e.g. because no memory
  705. * was available for an array), then dst is emptied and initialized to prevent
  706. * memory leaks.
  707. *
  708. * @param src The memory location of the source variable
  709. * @param dst The memory location of the destination variable
  710. * @param type The datatype description
  711. * @return Indicates whether the operation succeeded or returns an error code */
  712. UA_StatusCode UA_EXPORT
  713. UA_copy(const void *src, void *dst, const UA_DataType *type);
  714. /* Deletes the dynamically allocated content of a variable (e.g. resets all
  715. * arrays to undefined arrays). Afterwards, the variable can be safely deleted
  716. * without causing memory leaks. But the variable is not initialized and may
  717. * contain old data that is not memory-relevant.
  718. *
  719. * @param p The memory location of the variable
  720. * @param type The datatype description of the variable */
  721. void UA_EXPORT UA_deleteMembers(void *p, const UA_DataType *type);
  722. /* Frees a variable and all of its content.
  723. *
  724. * @param p The memory location of the variable
  725. * @param type The datatype description of the variable */
  726. void UA_EXPORT UA_delete(void *p, const UA_DataType *type);
  727. /**
  728. * .. _array-handling:
  729. *
  730. * Array handling
  731. * --------------
  732. * In OPC UA, arrays can have a length of zero or more with the usual meaning.
  733. * In addition, arrays can be undefined. Then, they don't even have a length. In
  734. * the binary encoding, this is indicated by an array of length -1.
  735. *
  736. * In open62541 however, we use ``size_t`` for array lengths. An undefined array
  737. * has length 0 and the data pointer is ``NULL``. An array of length 0 also has
  738. * length 0 but a data pointer ``UA_EMPTY_ARRAY_SENTINEL``. */
  739. /* Allocates and initializes an array of variables of a specific type
  740. *
  741. * @param size The requested array length
  742. * @param type The datatype description
  743. * @return Returns the memory location of the variable or NULL if no memory
  744. could be allocated */
  745. void UA_EXPORT * UA_Array_new(size_t size, const UA_DataType *type) UA_FUNC_ATTR_MALLOC;
  746. /* Allocates and copies an array
  747. *
  748. * @param src The memory location of the source array
  749. * @param size The size of the array
  750. * @param dst The location of the pointer to the new array
  751. * @param type The datatype of the array members
  752. * @return Returns UA_STATUSCODE_GOOD or UA_STATUSCODE_BADOUTOFMEMORY */
  753. UA_StatusCode UA_EXPORT
  754. UA_Array_copy(const void *src, size_t size, void **dst,
  755. const UA_DataType *type) UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  756. /* Deletes an array.
  757. *
  758. * @param p The memory location of the array
  759. * @param size The size of the array
  760. * @param type The datatype of the array members */
  761. void UA_EXPORT UA_Array_delete(void *p, size_t size, const UA_DataType *type);
  762. /**
  763. * .. _numericrange:
  764. *
  765. * NumericRange
  766. * ^^^^^^^^^^^^
  767. *
  768. * NumericRanges are used to indicate subsets of a (multidimensional) variant
  769. * array. NumericRange has no official type structure in the standard. On the
  770. * wire, it only exists as an encoded string, such as "1:2,0:3,5". The colon
  771. * separates min/max index and the comma separates dimensions. A single value
  772. * indicates a range with a single element (min==max). */
  773. typedef struct {
  774. UA_UInt32 min;
  775. UA_UInt32 max;
  776. } UA_NumericRangeDimension;
  777. struct UA_NumericRange {
  778. size_t dimensionsSize;
  779. UA_NumericRangeDimension *dimensions;
  780. };
  781. /**
  782. * Random Number Generator
  783. * -----------------------
  784. * If UA_ENABLE_MULTITHREADING is defined, then the seed is stored in thread
  785. * local storage. The seed is initialized for every thread in the
  786. * server/client. */
  787. void UA_EXPORT UA_random_seed(UA_UInt64 seed);
  788. UA_UInt32 UA_EXPORT UA_UInt32_random(void); /* no cryptographic entropy */
  789. UA_Guid UA_EXPORT UA_Guid_random(void); /* no cryptographic entropy */
  790. /**
  791. * .. _generated-types:
  792. *
  793. * Generated Data Type Definitions
  794. * -------------------------------
  795. *
  796. * The following data types were auto-generated from a definition in XML format.
  797. *
  798. * .. toctree::
  799. *
  800. * types_generated */
  801. #ifdef __cplusplus
  802. } // extern "C"
  803. #endif
  804. #endif /* UA_TYPES_H_ */