types.h 35 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026
  1. /* This Source Code Form is subject to the terms of the Mozilla Public
  2. * License, v. 2.0. If a copy of the MPL was not distributed with this
  3. * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  4. *
  5. * Copyright 2014 (c) Leon Urbas
  6. * Copyright 2014, 2016-2017 (c) Florian Palm
  7. * Copyright 2014-2017 (c) Fraunhofer IOSB (Author: Julius Pfrommer)
  8. * Copyright 2015-2016 (c) Sten Grüner
  9. * Copyright 2015-2016 (c) Chris Iatrou
  10. * Copyright 2015 (c) Nick Goossens
  11. * Copyright 2015-2016 (c) Oleksiy Vasylyev
  12. * Copyright 2017 (c) Stefan Profanter, fortiss GmbH
  13. * Copyright 2017 (c) Thomas Stalder, Blue Time Concept SA
  14. */
  15. #ifndef UA_TYPES_H_
  16. #define UA_TYPES_H_
  17. #include <open62541/config.h>
  18. #include <open62541/constants.h>
  19. #include <open62541/statuscodes.h>
  20. _UA_BEGIN_DECLS
  21. #define UA_BUILTIN_TYPES_COUNT 25U
  22. /**
  23. * .. _types:
  24. *
  25. * Data Types
  26. * ==========
  27. *
  28. * The OPC UA protocol defines 25 builtin data types and three ways of combining
  29. * them into higher-order types: arrays, structures and unions. In open62541,
  30. * only the builtin data types are defined manually. All other data types are
  31. * generated from standard XML definitions. Their exact definitions can be
  32. * looked up at https://opcfoundation.org/UA/schemas/Opc.Ua.Types.bsd.
  33. *
  34. * For users that are new to open62541, take a look at the :ref:`tutorial for
  35. * working with data types<types-tutorial>` before diving into the
  36. * implementation details.
  37. *
  38. * Builtin Types
  39. * -------------
  40. *
  41. * Boolean
  42. * ^^^^^^^
  43. * A two-state logical value (true or false). */
  44. typedef bool UA_Boolean;
  45. #define UA_TRUE true UA_INTERNAL_DEPRECATED
  46. #define UA_FALSE false UA_INTERNAL_DEPRECATED
  47. /**
  48. * SByte
  49. * ^^^^^
  50. * An integer value between -128 and 127. */
  51. typedef int8_t UA_SByte;
  52. #define UA_SBYTE_MIN (-128)
  53. #define UA_SBYTE_MAX 127
  54. /**
  55. * Byte
  56. * ^^^^
  57. * An integer value between 0 and 255. */
  58. typedef uint8_t UA_Byte;
  59. #define UA_BYTE_MIN 0
  60. #define UA_BYTE_MAX 255
  61. /**
  62. * Int16
  63. * ^^^^^
  64. * An integer value between -32 768 and 32 767. */
  65. typedef int16_t UA_Int16;
  66. #define UA_INT16_MIN (-32768)
  67. #define UA_INT16_MAX 32767
  68. /**
  69. * UInt16
  70. * ^^^^^^
  71. * An integer value between 0 and 65 535. */
  72. typedef uint16_t UA_UInt16;
  73. #define UA_UINT16_MIN 0
  74. #define UA_UINT16_MAX 65535
  75. /**
  76. * Int32
  77. * ^^^^^
  78. * An integer value between -2 147 483 648 and 2 147 483 647. */
  79. typedef int32_t UA_Int32;
  80. #define UA_INT32_MIN (-2147483648)
  81. #define UA_INT32_MAX 2147483647
  82. /**
  83. * UInt32
  84. * ^^^^^^
  85. * An integer value between 0 and 4 294 967 295. */
  86. typedef uint32_t UA_UInt32;
  87. #define UA_UINT32_MIN 0
  88. #define UA_UINT32_MAX 4294967295
  89. /**
  90. * Int64
  91. * ^^^^^
  92. * An integer value between -9 223 372 036 854 775 808 and
  93. * 9 223 372 036 854 775 807. */
  94. typedef int64_t UA_Int64;
  95. #define UA_INT64_MAX (int64_t)9223372036854775807LL
  96. #define UA_INT64_MIN ((int64_t)-UA_INT64_MAX-1LL)
  97. /**
  98. * UInt64
  99. * ^^^^^^
  100. * An integer value between 0 and 18 446 744 073 709 551 615. */
  101. typedef uint64_t UA_UInt64;
  102. #define UA_UINT64_MIN (uint64_t)0
  103. #define UA_UINT64_MAX (uint64_t)18446744073709551615ULL
  104. /**
  105. * Float
  106. * ^^^^^
  107. * An IEEE single precision (32 bit) floating point value. */
  108. typedef float UA_Float;
  109. /**
  110. * Double
  111. * ^^^^^^
  112. * An IEEE double precision (64 bit) floating point value. */
  113. typedef double UA_Double;
  114. /**
  115. * .. _statuscode:
  116. *
  117. * StatusCode
  118. * ^^^^^^^^^^
  119. * A numeric identifier for a error or condition that is associated with a value
  120. * or an operation. See the section :ref:`statuscodes` for the meaning of a
  121. * specific code. */
  122. typedef uint32_t UA_StatusCode;
  123. /* Returns the human-readable name of the StatusCode. If no matching StatusCode
  124. * is found, a default string for "Unknown" is returned. This feature might be
  125. * disabled to create a smaller binary with the
  126. * UA_ENABLE_STATUSCODE_DESCRIPTIONS build-flag. Then the function returns an
  127. * empty string for every StatusCode. */
  128. UA_EXPORT const char *
  129. UA_StatusCode_name(UA_StatusCode code);
  130. /**
  131. * String
  132. * ^^^^^^
  133. * A sequence of Unicode characters. Strings are just an array of UA_Byte. */
  134. typedef struct {
  135. size_t length; /* The length of the string */
  136. UA_Byte *data; /* The content (not null-terminated) */
  137. } UA_String;
  138. /* Copies the content on the heap. Returns a null-string when alloc fails */
  139. UA_String UA_EXPORT UA_String_fromChars(const char *src) UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  140. UA_Boolean UA_EXPORT UA_String_equal(const UA_String *s1, const UA_String *s2);
  141. UA_EXPORT extern const UA_String UA_STRING_NULL;
  142. /**
  143. * ``UA_STRING`` returns a string pointing to the original char-array.
  144. * ``UA_STRING_ALLOC`` is shorthand for ``UA_String_fromChars`` and makes a copy
  145. * of the char-array. */
  146. static UA_INLINE UA_String
  147. UA_STRING(char *chars) {
  148. UA_String s; s.length = 0; s.data = NULL;
  149. if(!chars)
  150. return s;
  151. s.length = strlen(chars); s.data = (UA_Byte*)chars; return s;
  152. }
  153. #define UA_STRING_ALLOC(CHARS) UA_String_fromChars(CHARS)
  154. /* Define strings at compile time (in ROM) */
  155. #define UA_STRING_STATIC(CHARS) {sizeof(CHARS)-1, (UA_Byte*)CHARS}
  156. /**
  157. * .. _datetime:
  158. *
  159. * DateTime
  160. * ^^^^^^^^
  161. * An instance in time. A DateTime value is encoded as a 64-bit signed integer
  162. * which represents the number of 100 nanosecond intervals since January 1, 1601
  163. * (UTC).
  164. *
  165. * The methods providing an interface to the system clock are architecture-
  166. * specific. Usually, they provide a UTC clock that includes leap seconds. The
  167. * OPC UA standard allows the use of International Atomic Time (TAI) for the
  168. * DateTime instead. But this is still unusual and not implemented for most
  169. * SDKs. Currently (2019), UTC and TAI are 37 seconds apart due to leap
  170. * seconds. */
  171. typedef int64_t UA_DateTime;
  172. /* Multiples to convert durations to DateTime */
  173. #define UA_DATETIME_USEC 10LL
  174. #define UA_DATETIME_MSEC (UA_DATETIME_USEC * 1000LL)
  175. #define UA_DATETIME_SEC (UA_DATETIME_MSEC * 1000LL)
  176. /* The current time in UTC time */
  177. UA_DateTime UA_EXPORT UA_DateTime_now(void);
  178. /* Offset between local time and UTC time */
  179. UA_Int64 UA_EXPORT UA_DateTime_localTimeUtcOffset(void);
  180. /* CPU clock invariant to system time changes. Use only to measure durations,
  181. * not absolute time. */
  182. UA_DateTime UA_EXPORT UA_DateTime_nowMonotonic(void);
  183. /* Represents a Datetime as a structure */
  184. typedef struct UA_DateTimeStruct {
  185. UA_UInt16 nanoSec;
  186. UA_UInt16 microSec;
  187. UA_UInt16 milliSec;
  188. UA_UInt16 sec;
  189. UA_UInt16 min;
  190. UA_UInt16 hour;
  191. UA_UInt16 day; /* From 1 to 31 */
  192. UA_UInt16 month; /* From 1 to 12 */
  193. UA_UInt16 year;
  194. } UA_DateTimeStruct;
  195. UA_DateTimeStruct UA_EXPORT UA_DateTime_toStruct(UA_DateTime t);
  196. UA_DateTime UA_EXPORT UA_DateTime_fromStruct(UA_DateTimeStruct ts);
  197. /* The C99 standard (7.23.1) says: "The range and precision of times
  198. * representable in clock_t and time_t are implementation-defined." On most
  199. * systems, time_t is a 4 or 8 byte integer counting seconds since the UTC Unix
  200. * epoch. The following methods are used for conversion. */
  201. /* Datetime of 1 Jan 1970 00:00 */
  202. #define UA_DATETIME_UNIX_EPOCH (11644473600LL * UA_DATETIME_SEC)
  203. static UA_INLINE UA_Int64
  204. UA_DateTime_toUnixTime(UA_DateTime date) {
  205. return (date - UA_DATETIME_UNIX_EPOCH) / UA_DATETIME_SEC;
  206. }
  207. static UA_INLINE UA_DateTime
  208. UA_DateTime_fromUnixTime(UA_Int64 unixDate) {
  209. return (unixDate * UA_DATETIME_SEC) + UA_DATETIME_UNIX_EPOCH;
  210. }
  211. /**
  212. * Guid
  213. * ^^^^
  214. * A 16 byte value that can be used as a globally unique identifier. */
  215. typedef struct {
  216. UA_UInt32 data1;
  217. UA_UInt16 data2;
  218. UA_UInt16 data3;
  219. UA_Byte data4[8];
  220. } UA_Guid;
  221. UA_Boolean UA_EXPORT UA_Guid_equal(const UA_Guid *g1, const UA_Guid *g2);
  222. UA_EXPORT extern const UA_Guid UA_GUID_NULL;
  223. /**
  224. * ByteString
  225. * ^^^^^^^^^^
  226. * A sequence of octets. */
  227. typedef UA_String UA_ByteString;
  228. static UA_INLINE UA_Boolean
  229. UA_ByteString_equal(const UA_ByteString *string1,
  230. const UA_ByteString *string2) {
  231. return UA_String_equal((const UA_String*)string1,
  232. (const UA_String*)string2);
  233. }
  234. /* Allocates memory of size length for the bytestring.
  235. * The content is not set to zero. */
  236. UA_StatusCode UA_EXPORT
  237. UA_ByteString_allocBuffer(UA_ByteString *bs, size_t length);
  238. UA_EXPORT extern const UA_ByteString UA_BYTESTRING_NULL;
  239. static UA_INLINE UA_ByteString
  240. UA_BYTESTRING(char *chars) {
  241. UA_ByteString bs; bs.length = 0; bs.data = NULL;
  242. if(!chars)
  243. return bs;
  244. bs.length = strlen(chars); bs.data = (UA_Byte*)chars; return bs;
  245. }
  246. static UA_INLINE UA_ByteString
  247. UA_BYTESTRING_ALLOC(const char *chars) {
  248. UA_String str = UA_String_fromChars(chars); UA_ByteString bstr;
  249. bstr.length = str.length; bstr.data = str.data; return bstr;
  250. }
  251. /**
  252. * XmlElement
  253. * ^^^^^^^^^^
  254. * An XML element. */
  255. typedef UA_String UA_XmlElement;
  256. /**
  257. * .. _nodeid:
  258. *
  259. * NodeId
  260. * ^^^^^^
  261. * An identifier for a node in the address space of an OPC UA Server. */
  262. enum UA_NodeIdType {
  263. UA_NODEIDTYPE_NUMERIC = 0, /* In the binary encoding, this can also
  264. * become 1 or 2 (two-byte and four-byte
  265. * encoding of small numeric nodeids) */
  266. UA_NODEIDTYPE_STRING = 3,
  267. UA_NODEIDTYPE_GUID = 4,
  268. UA_NODEIDTYPE_BYTESTRING = 5
  269. };
  270. typedef struct {
  271. UA_UInt16 namespaceIndex;
  272. enum UA_NodeIdType identifierType;
  273. union {
  274. UA_UInt32 numeric;
  275. UA_String string;
  276. UA_Guid guid;
  277. UA_ByteString byteString;
  278. } identifier;
  279. } UA_NodeId;
  280. UA_EXPORT extern const UA_NodeId UA_NODEID_NULL;
  281. UA_Boolean UA_EXPORT UA_NodeId_isNull(const UA_NodeId *p);
  282. UA_Order UA_EXPORT UA_NodeId_order(const UA_NodeId *n1, const UA_NodeId *n2);
  283. static UA_INLINE UA_Boolean
  284. UA_NodeId_equal(const UA_NodeId *n1, const UA_NodeId *n2) {
  285. return (UA_NodeId_order(n1, n2) == UA_ORDER_EQ);
  286. }
  287. /* Returns a non-cryptographic hash for the NodeId */
  288. UA_UInt32 UA_EXPORT UA_NodeId_hash(const UA_NodeId *n);
  289. /** The following functions are shorthand for creating NodeIds. */
  290. static UA_INLINE UA_NodeId
  291. UA_NODEID_NUMERIC(UA_UInt16 nsIndex, UA_UInt32 identifier) {
  292. UA_NodeId id; id.namespaceIndex = nsIndex;
  293. id.identifierType = UA_NODEIDTYPE_NUMERIC;
  294. id.identifier.numeric = identifier; return id;
  295. }
  296. static UA_INLINE UA_NodeId
  297. UA_NODEID_STRING(UA_UInt16 nsIndex, char *chars) {
  298. UA_NodeId id; id.namespaceIndex = nsIndex;
  299. id.identifierType = UA_NODEIDTYPE_STRING;
  300. id.identifier.string = UA_STRING(chars); return id;
  301. }
  302. static UA_INLINE UA_NodeId
  303. UA_NODEID_STRING_ALLOC(UA_UInt16 nsIndex, const char *chars) {
  304. UA_NodeId id; id.namespaceIndex = nsIndex;
  305. id.identifierType = UA_NODEIDTYPE_STRING;
  306. id.identifier.string = UA_STRING_ALLOC(chars); return id;
  307. }
  308. static UA_INLINE UA_NodeId
  309. UA_NODEID_GUID(UA_UInt16 nsIndex, UA_Guid guid) {
  310. UA_NodeId id; id.namespaceIndex = nsIndex;
  311. id.identifierType = UA_NODEIDTYPE_GUID;
  312. id.identifier.guid = guid; return id;
  313. }
  314. static UA_INLINE UA_NodeId
  315. UA_NODEID_BYTESTRING(UA_UInt16 nsIndex, char *chars) {
  316. UA_NodeId id; id.namespaceIndex = nsIndex;
  317. id.identifierType = UA_NODEIDTYPE_BYTESTRING;
  318. id.identifier.byteString = UA_BYTESTRING(chars); return id;
  319. }
  320. static UA_INLINE UA_NodeId
  321. UA_NODEID_BYTESTRING_ALLOC(UA_UInt16 nsIndex, const char *chars) {
  322. UA_NodeId id; id.namespaceIndex = nsIndex;
  323. id.identifierType = UA_NODEIDTYPE_BYTESTRING;
  324. id.identifier.byteString = UA_BYTESTRING_ALLOC(chars); return id;
  325. }
  326. /**
  327. * ExpandedNodeId
  328. * ^^^^^^^^^^^^^^
  329. * A NodeId that allows the namespace URI to be specified instead of an index. */
  330. typedef struct {
  331. UA_NodeId nodeId;
  332. UA_String namespaceUri;
  333. UA_UInt32 serverIndex;
  334. } UA_ExpandedNodeId;
  335. UA_EXPORT extern const UA_ExpandedNodeId UA_EXPANDEDNODEID_NULL;
  336. UA_Order UA_EXPORT
  337. UA_ExpandedNodeId_order(const UA_ExpandedNodeId *n1, const UA_ExpandedNodeId *n2);
  338. static UA_INLINE UA_Boolean
  339. UA_ExpandedNodeId_equal(const UA_ExpandedNodeId *n1, const UA_ExpandedNodeId *n2) {
  340. return (UA_ExpandedNodeId_order(n1, n2) == UA_ORDER_EQ);
  341. }
  342. /* Returns a non-cryptographic hash for the NodeId */
  343. UA_UInt32 UA_EXPORT UA_ExpandedNodeId_hash(const UA_ExpandedNodeId *n);
  344. /** The following functions are shorthand for creating ExpandedNodeIds. */
  345. static UA_INLINE UA_ExpandedNodeId
  346. UA_EXPANDEDNODEID_NUMERIC(UA_UInt16 nsIndex, UA_UInt32 identifier) {
  347. UA_ExpandedNodeId id; id.nodeId = UA_NODEID_NUMERIC(nsIndex, identifier);
  348. id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
  349. }
  350. static UA_INLINE UA_ExpandedNodeId
  351. UA_EXPANDEDNODEID_STRING(UA_UInt16 nsIndex, char *chars) {
  352. UA_ExpandedNodeId id; id.nodeId = UA_NODEID_STRING(nsIndex, chars);
  353. id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
  354. }
  355. static UA_INLINE UA_ExpandedNodeId
  356. UA_EXPANDEDNODEID_STRING_ALLOC(UA_UInt16 nsIndex, const char *chars) {
  357. UA_ExpandedNodeId id; id.nodeId = UA_NODEID_STRING_ALLOC(nsIndex, chars);
  358. id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
  359. }
  360. static UA_INLINE UA_ExpandedNodeId
  361. UA_EXPANDEDNODEID_STRING_GUID(UA_UInt16 nsIndex, UA_Guid guid) {
  362. UA_ExpandedNodeId id; id.nodeId = UA_NODEID_GUID(nsIndex, guid);
  363. id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
  364. }
  365. static UA_INLINE UA_ExpandedNodeId
  366. UA_EXPANDEDNODEID_BYTESTRING(UA_UInt16 nsIndex, char *chars) {
  367. UA_ExpandedNodeId id; id.nodeId = UA_NODEID_BYTESTRING(nsIndex, chars);
  368. id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
  369. }
  370. static UA_INLINE UA_ExpandedNodeId
  371. UA_EXPANDEDNODEID_BYTESTRING_ALLOC(UA_UInt16 nsIndex, const char *chars) {
  372. UA_ExpandedNodeId id; id.nodeId = UA_NODEID_BYTESTRING_ALLOC(nsIndex, chars);
  373. id.serverIndex = 0; id.namespaceUri = UA_STRING_NULL; return id;
  374. }
  375. /**
  376. * .. _qualifiedname:
  377. *
  378. * QualifiedName
  379. * ^^^^^^^^^^^^^
  380. * A name qualified by a namespace. */
  381. typedef struct {
  382. UA_UInt16 namespaceIndex;
  383. UA_String name;
  384. } UA_QualifiedName;
  385. static UA_INLINE UA_Boolean
  386. UA_QualifiedName_isNull(const UA_QualifiedName *q) {
  387. return (q->namespaceIndex == 0 && q->name.length == 0);
  388. }
  389. static UA_INLINE UA_QualifiedName
  390. UA_QUALIFIEDNAME(UA_UInt16 nsIndex, char *chars) {
  391. UA_QualifiedName qn; qn.namespaceIndex = nsIndex;
  392. qn.name = UA_STRING(chars); return qn;
  393. }
  394. static UA_INLINE UA_QualifiedName
  395. UA_QUALIFIEDNAME_ALLOC(UA_UInt16 nsIndex, const char *chars) {
  396. UA_QualifiedName qn; qn.namespaceIndex = nsIndex;
  397. qn.name = UA_STRING_ALLOC(chars); return qn;
  398. }
  399. UA_Boolean UA_EXPORT
  400. UA_QualifiedName_equal(const UA_QualifiedName *qn1,
  401. const UA_QualifiedName *qn2);
  402. /**
  403. * LocalizedText
  404. * ^^^^^^^^^^^^^
  405. * Human readable text with an optional locale identifier. */
  406. typedef struct {
  407. UA_String locale;
  408. UA_String text;
  409. } UA_LocalizedText;
  410. static UA_INLINE UA_LocalizedText
  411. UA_LOCALIZEDTEXT(char *locale, char *text) {
  412. UA_LocalizedText lt; lt.locale = UA_STRING(locale);
  413. lt.text = UA_STRING(text); return lt;
  414. }
  415. static UA_INLINE UA_LocalizedText
  416. UA_LOCALIZEDTEXT_ALLOC(const char *locale, const char *text) {
  417. UA_LocalizedText lt; lt.locale = UA_STRING_ALLOC(locale);
  418. lt.text = UA_STRING_ALLOC(text); return lt;
  419. }
  420. /**
  421. * .. _numericrange:
  422. *
  423. * NumericRange
  424. * ^^^^^^^^^^^^
  425. *
  426. * NumericRanges are used to indicate subsets of a (multidimensional) array.
  427. * They no official data type in the OPC UA standard and are transmitted only
  428. * with a string encoding, such as "1:2,0:3,5". The colon separates min/max
  429. * index and the comma separates dimensions. A single value indicates a range
  430. * with a single element (min==max). */
  431. typedef struct {
  432. UA_UInt32 min;
  433. UA_UInt32 max;
  434. } UA_NumericRangeDimension;
  435. typedef struct {
  436. size_t dimensionsSize;
  437. UA_NumericRangeDimension *dimensions;
  438. } UA_NumericRange;
  439. UA_StatusCode UA_EXPORT
  440. UA_NumericRange_parseFromString(UA_NumericRange *range, const UA_String *str);
  441. /**
  442. * .. _variant:
  443. *
  444. * Variant
  445. * ^^^^^^^
  446. *
  447. * Variants may contain values of any type together with a description of the
  448. * content. See the section on :ref:`generic-types` on how types are described.
  449. * The standard mandates that variants contain built-in data types only. If the
  450. * value is not of a builtin type, it is wrapped into an :ref:`extensionobject`.
  451. * open62541 hides this wrapping transparently in the encoding layer. If the
  452. * data type is unknown to the receiver, the variant contains the original
  453. * ExtensionObject in binary or XML encoding.
  454. *
  455. * Variants may contain a scalar value or an array. For details on the handling
  456. * of arrays, see the section on :ref:`array-handling`. Array variants can have
  457. * an additional dimensionality (matrix, 3-tensor, ...) defined in an array of
  458. * dimension lengths. The actual values are kept in an array of dimensions one.
  459. * For users who work with higher-dimensions arrays directly, keep in mind that
  460. * dimensions of higher rank are serialized first (the highest rank dimension
  461. * has stride 1 and elements follow each other directly). Usually it is simplest
  462. * to interact with higher-dimensional arrays via ``UA_NumericRange``
  463. * descriptions (see :ref:`array-handling`).
  464. *
  465. * To differentiate between scalar / array variants, the following definition is
  466. * used. ``UA_Variant_isScalar`` provides simplified access to these checks.
  467. *
  468. * - ``arrayLength == 0 && data == NULL``: undefined array of length -1
  469. * - ``arrayLength == 0 && data == UA_EMPTY_ARRAY_SENTINEL``: array of length 0
  470. * - ``arrayLength == 0 && data > UA_EMPTY_ARRAY_SENTINEL``: scalar value
  471. * - ``arrayLength > 0``: array of the given length
  472. *
  473. * Variants can also be *empty*. Then, the pointer to the type description is
  474. * ``NULL``. */
  475. /* Forward declaration. See the section on Generic Type Handling */
  476. struct UA_DataType;
  477. typedef struct UA_DataType UA_DataType;
  478. #define UA_EMPTY_ARRAY_SENTINEL ((void*)0x01)
  479. typedef enum {
  480. UA_VARIANT_DATA, /* The data has the same lifecycle as the
  481. variant */
  482. UA_VARIANT_DATA_NODELETE /* The data is "borrowed" by the variant and
  483. shall not be deleted at the end of the
  484. variant's lifecycle. */
  485. } UA_VariantStorageType;
  486. typedef struct {
  487. const UA_DataType *type; /* The data type description */
  488. UA_VariantStorageType storageType;
  489. size_t arrayLength; /* The number of elements in the data array */
  490. void *data; /* Points to the scalar or array data */
  491. size_t arrayDimensionsSize; /* The number of dimensions */
  492. UA_UInt32 *arrayDimensions; /* The length of each dimension */
  493. } UA_Variant;
  494. /* Returns true if the variant has no value defined (contains neither an array
  495. * nor a scalar value).
  496. *
  497. * @param v The variant
  498. * @return Is the variant empty */
  499. static UA_INLINE UA_Boolean
  500. UA_Variant_isEmpty(const UA_Variant *v) {
  501. return v->type == NULL;
  502. }
  503. /* Returns true if the variant contains a scalar value. Note that empty variants
  504. * contain an array of length -1 (undefined).
  505. *
  506. * @param v The variant
  507. * @return Does the variant contain a scalar value */
  508. static UA_INLINE UA_Boolean
  509. UA_Variant_isScalar(const UA_Variant *v) {
  510. return (v->arrayLength == 0 && v->data > UA_EMPTY_ARRAY_SENTINEL);
  511. }
  512. /* Returns true if the variant contains a scalar value of the given type.
  513. *
  514. * @param v The variant
  515. * @param type The data type
  516. * @return Does the variant contain a scalar value of the given type */
  517. static UA_INLINE UA_Boolean
  518. UA_Variant_hasScalarType(const UA_Variant *v, const UA_DataType *type) {
  519. return UA_Variant_isScalar(v) && type == v->type;
  520. }
  521. /* Returns true if the variant contains an array of the given type.
  522. *
  523. * @param v The variant
  524. * @param type The data type
  525. * @return Does the variant contain an array of the given type */
  526. static UA_INLINE UA_Boolean
  527. UA_Variant_hasArrayType(const UA_Variant *v, const UA_DataType *type) {
  528. return (!UA_Variant_isScalar(v)) && type == v->type;
  529. }
  530. /* Set the variant to a scalar value that already resides in memory. The value
  531. * takes on the lifecycle of the variant and is deleted with it.
  532. *
  533. * @param v The variant
  534. * @param p A pointer to the value data
  535. * @param type The datatype of the value in question */
  536. void UA_EXPORT
  537. UA_Variant_setScalar(UA_Variant *v, void * UA_RESTRICT p,
  538. const UA_DataType *type);
  539. /* Set the variant to a scalar value that is copied from an existing variable.
  540. * @param v The variant
  541. * @param p A pointer to the value data
  542. * @param type The datatype of the value
  543. * @return Indicates whether the operation succeeded or returns an error code */
  544. UA_StatusCode UA_EXPORT
  545. UA_Variant_setScalarCopy(UA_Variant *v, const void *p,
  546. const UA_DataType *type);
  547. /* Set the variant to an array that already resides in memory. The array takes
  548. * on the lifecycle of the variant and is deleted with it.
  549. *
  550. * @param v The variant
  551. * @param array A pointer to the array data
  552. * @param arraySize The size of the array
  553. * @param type The datatype of the array */
  554. void UA_EXPORT
  555. UA_Variant_setArray(UA_Variant *v, void * UA_RESTRICT array,
  556. size_t arraySize, const UA_DataType *type);
  557. /* Set the variant to an array that is copied from an existing array.
  558. *
  559. * @param v The variant
  560. * @param array A pointer to the array data
  561. * @param arraySize The size of the array
  562. * @param type The datatype of the array
  563. * @return Indicates whether the operation succeeded or returns an error code */
  564. UA_StatusCode UA_EXPORT
  565. UA_Variant_setArrayCopy(UA_Variant *v, const void *array,
  566. size_t arraySize, const UA_DataType *type);
  567. /* Copy the variant, but use only a subset of the (multidimensional) array into
  568. * a variant. Returns an error code if the variant is not an array or if the
  569. * indicated range does not fit.
  570. *
  571. * @param src The source variant
  572. * @param dst The target variant
  573. * @param range The range of the copied data
  574. * @return Returns UA_STATUSCODE_GOOD or an error code */
  575. UA_StatusCode UA_EXPORT
  576. UA_Variant_copyRange(const UA_Variant *src, UA_Variant *dst,
  577. const UA_NumericRange range);
  578. /* Insert a range of data into an existing variant. The data array can't be
  579. * reused afterwards if it contains types without a fixed size (e.g. strings)
  580. * since the members are moved into the variant and take on its lifecycle.
  581. *
  582. * @param v The variant
  583. * @param dataArray The data array. The type must match the variant
  584. * @param dataArraySize The length of the data array. This is checked to match
  585. * the range size.
  586. * @param range The range of where the new data is inserted
  587. * @return Returns UA_STATUSCODE_GOOD or an error code */
  588. UA_StatusCode UA_EXPORT
  589. UA_Variant_setRange(UA_Variant *v, void * UA_RESTRICT array,
  590. size_t arraySize, const UA_NumericRange range);
  591. /* Deep-copy a range of data into an existing variant.
  592. *
  593. * @param v The variant
  594. * @param dataArray The data array. The type must match the variant
  595. * @param dataArraySize The length of the data array. This is checked to match
  596. * the range size.
  597. * @param range The range of where the new data is inserted
  598. * @return Returns UA_STATUSCODE_GOOD or an error code */
  599. UA_StatusCode UA_EXPORT
  600. UA_Variant_setRangeCopy(UA_Variant *v, const void *array,
  601. size_t arraySize, const UA_NumericRange range);
  602. /**
  603. * .. _extensionobject:
  604. *
  605. * ExtensionObject
  606. * ^^^^^^^^^^^^^^^
  607. *
  608. * ExtensionObjects may contain scalars of any data type. Even those that are
  609. * unknown to the receiver. See the section on :ref:`generic-types` on how types
  610. * are described. If the received data type is unknown, the encoded string and
  611. * target NodeId is stored instead of the decoded value. */
  612. typedef enum {
  613. UA_EXTENSIONOBJECT_ENCODED_NOBODY = 0,
  614. UA_EXTENSIONOBJECT_ENCODED_BYTESTRING = 1,
  615. UA_EXTENSIONOBJECT_ENCODED_XML = 2,
  616. UA_EXTENSIONOBJECT_DECODED = 3,
  617. UA_EXTENSIONOBJECT_DECODED_NODELETE = 4 /* Don't delete the content
  618. together with the
  619. ExtensionObject */
  620. } UA_ExtensionObjectEncoding;
  621. typedef struct {
  622. UA_ExtensionObjectEncoding encoding;
  623. union {
  624. struct {
  625. UA_NodeId typeId; /* The nodeid of the datatype */
  626. UA_ByteString body; /* The bytestring of the encoded data */
  627. } encoded;
  628. struct {
  629. const UA_DataType *type;
  630. void *data;
  631. } decoded;
  632. } content;
  633. } UA_ExtensionObject;
  634. /**
  635. * .. _datavalue:
  636. *
  637. * DataValue
  638. * ^^^^^^^^^
  639. * A data value with an associated status code and timestamps. */
  640. typedef struct {
  641. UA_Variant value;
  642. UA_DateTime sourceTimestamp;
  643. UA_DateTime serverTimestamp;
  644. UA_UInt16 sourcePicoseconds;
  645. UA_UInt16 serverPicoseconds;
  646. UA_StatusCode status;
  647. UA_Boolean hasValue : 1;
  648. UA_Boolean hasStatus : 1;
  649. UA_Boolean hasSourceTimestamp : 1;
  650. UA_Boolean hasServerTimestamp : 1;
  651. UA_Boolean hasSourcePicoseconds : 1;
  652. UA_Boolean hasServerPicoseconds : 1;
  653. } UA_DataValue;
  654. /**
  655. * DiagnosticInfo
  656. * ^^^^^^^^^^^^^^
  657. * A structure that contains detailed error and diagnostic information
  658. * associated with a StatusCode. */
  659. typedef struct UA_DiagnosticInfo {
  660. UA_Boolean hasSymbolicId : 1;
  661. UA_Boolean hasNamespaceUri : 1;
  662. UA_Boolean hasLocalizedText : 1;
  663. UA_Boolean hasLocale : 1;
  664. UA_Boolean hasAdditionalInfo : 1;
  665. UA_Boolean hasInnerStatusCode : 1;
  666. UA_Boolean hasInnerDiagnosticInfo : 1;
  667. UA_Int32 symbolicId;
  668. UA_Int32 namespaceUri;
  669. UA_Int32 localizedText;
  670. UA_Int32 locale;
  671. UA_String additionalInfo;
  672. UA_StatusCode innerStatusCode;
  673. struct UA_DiagnosticInfo *innerDiagnosticInfo;
  674. } UA_DiagnosticInfo;
  675. /**
  676. * .. _generic-types:
  677. *
  678. * Generic Type Handling
  679. * ---------------------
  680. *
  681. * All information about a (builtin/structured) data type is stored in a
  682. * ``UA_DataType``. The array ``UA_TYPES`` contains the description of all
  683. * standard-defined types. This type description is used for the following
  684. * generic operations that work on all types:
  685. *
  686. * - ``void T_init(T *ptr)``: Initialize the data type. This is synonymous with
  687. * zeroing out the memory, i.e. ``memset(ptr, 0, sizeof(T))``.
  688. * - ``T* T_new()``: Allocate and return the memory for the data type. The
  689. * value is already initialized.
  690. * - ``UA_StatusCode T_copy(const T *src, T *dst)``: Copy the content of the
  691. * data type. Returns ``UA_STATUSCODE_GOOD`` or
  692. * ``UA_STATUSCODE_BADOUTOFMEMORY``.
  693. * - ``void T_clear(T *ptr)``: Delete the dynamically allocated content
  694. * of the data type and perform a ``T_init`` to reset the type.
  695. * - ``void T_delete(T *ptr)``: Delete the content of the data type and the
  696. * memory for the data type itself.
  697. *
  698. * Specializations, such as ``UA_Int32_new()`` are derived from the generic
  699. * type operations as static inline functions. */
  700. typedef struct {
  701. #ifdef UA_ENABLE_TYPEDESCRIPTION
  702. const char *memberName;
  703. #endif
  704. UA_UInt16 memberTypeIndex; /* Index of the member in the array of data
  705. types */
  706. UA_Byte padding; /* How much padding is there before this
  707. member element? For arrays this is the
  708. padding before the size_t length member.
  709. (No padding between size_t and the
  710. following ptr.) */
  711. UA_Boolean namespaceZero : 1; /* The type of the member is defined in
  712. namespace zero. In this implementation,
  713. types from custom namespace may contain
  714. members from the same namespace or
  715. namespace zero only.*/
  716. UA_Boolean isArray : 1; /* The member is an array */
  717. } UA_DataTypeMember;
  718. /* The DataType "kind" is an internal type classification. It is used to
  719. * dispatch handling to the correct routines. */
  720. #define UA_DATATYPEKINDS 31
  721. typedef enum {
  722. UA_DATATYPEKIND_BOOLEAN = 0,
  723. UA_DATATYPEKIND_SBYTE = 1,
  724. UA_DATATYPEKIND_BYTE = 2,
  725. UA_DATATYPEKIND_INT16 = 3,
  726. UA_DATATYPEKIND_UINT16 = 4,
  727. UA_DATATYPEKIND_INT32 = 5,
  728. UA_DATATYPEKIND_UINT32 = 6,
  729. UA_DATATYPEKIND_INT64 = 7,
  730. UA_DATATYPEKIND_UINT64 = 8,
  731. UA_DATATYPEKIND_FLOAT = 9,
  732. UA_DATATYPEKIND_DOUBLE = 10,
  733. UA_DATATYPEKIND_STRING = 11,
  734. UA_DATATYPEKIND_DATETIME = 12,
  735. UA_DATATYPEKIND_GUID = 13,
  736. UA_DATATYPEKIND_BYTESTRING = 14,
  737. UA_DATATYPEKIND_XMLELEMENT = 15,
  738. UA_DATATYPEKIND_NODEID = 16,
  739. UA_DATATYPEKIND_EXPANDEDNODEID = 17,
  740. UA_DATATYPEKIND_STATUSCODE = 18,
  741. UA_DATATYPEKIND_QUALIFIEDNAME = 19,
  742. UA_DATATYPEKIND_LOCALIZEDTEXT = 20,
  743. UA_DATATYPEKIND_EXTENSIONOBJECT = 21,
  744. UA_DATATYPEKIND_DATAVALUE = 22,
  745. UA_DATATYPEKIND_VARIANT = 23,
  746. UA_DATATYPEKIND_DIAGNOSTICINFO = 24,
  747. UA_DATATYPEKIND_DECIMAL = 25,
  748. UA_DATATYPEKIND_ENUM = 26,
  749. UA_DATATYPEKIND_STRUCTURE = 27,
  750. UA_DATATYPEKIND_OPTSTRUCT = 28, /* struct with optional fields */
  751. UA_DATATYPEKIND_UNION = 29,
  752. UA_DATATYPEKIND_BITFIELDCLUSTER = 30 /* bitfields + padding */
  753. } UA_DataTypeKind;
  754. struct UA_DataType {
  755. #ifdef UA_ENABLE_TYPEDESCRIPTION
  756. const char *typeName;
  757. #endif
  758. UA_NodeId typeId; /* The nodeid of the type */
  759. UA_UInt16 memSize; /* Size of the struct in memory */
  760. UA_UInt16 typeIndex; /* Index of the type in the datatypetable */
  761. UA_UInt32 typeKind : 6; /* Dispatch index for the handling routines */
  762. UA_UInt32 pointerFree : 1; /* The type (and its members) contains no
  763. * pointers that need to be freed */
  764. UA_UInt32 overlayable : 1; /* The type has the identical memory layout
  765. * in memory and on the binary stream. */
  766. UA_UInt32 membersSize : 8; /* How many members does the type have? */
  767. UA_UInt32 binaryEncodingId; /* NodeId of datatype when encoded as binary */
  768. //UA_UInt16 xmlEncodingId; /* NodeId of datatype when encoded as XML */
  769. UA_DataTypeMember *members;
  770. };
  771. /* Test if the data type is a numeric builtin data type. This includes Boolean,
  772. * integers and floating point numbers. Not included are DateTime and
  773. * StatusCode. */
  774. UA_Boolean
  775. UA_DataType_isNumeric(const UA_DataType *type);
  776. /**
  777. * Builtin data types can be accessed as UA_TYPES[UA_TYPES_XXX], where XXX is
  778. * the name of the data type. If only the NodeId of a type is known, use the
  779. * following method to retrieve the data type description. */
  780. /* Returns the data type description for the type's identifier or NULL if no
  781. * matching data type was found. */
  782. const UA_DataType UA_EXPORT *
  783. UA_findDataType(const UA_NodeId *typeId);
  784. /** The following functions are used for generic handling of data types. */
  785. /* Allocates and initializes a variable of type dataType
  786. *
  787. * @param type The datatype description
  788. * @return Returns the memory location of the variable or NULL if no
  789. * memory could be allocated */
  790. void UA_EXPORT * UA_new(const UA_DataType *type) UA_FUNC_ATTR_MALLOC;
  791. /* Initializes a variable to default values
  792. *
  793. * @param p The memory location of the variable
  794. * @param type The datatype description */
  795. static UA_INLINE void
  796. UA_init(void *p, const UA_DataType *type) {
  797. memset(p, 0, type->memSize);
  798. }
  799. /* Copies the content of two variables. If copying fails (e.g. because no memory
  800. * was available for an array), then dst is emptied and initialized to prevent
  801. * memory leaks.
  802. *
  803. * @param src The memory location of the source variable
  804. * @param dst The memory location of the destination variable
  805. * @param type The datatype description
  806. * @return Indicates whether the operation succeeded or returns an error code */
  807. UA_StatusCode UA_EXPORT
  808. UA_copy(const void *src, void *dst, const UA_DataType *type);
  809. /* Deletes the dynamically allocated content of a variable (e.g. resets all
  810. * arrays to undefined arrays). Afterwards, the variable can be safely deleted
  811. * without causing memory leaks. But the variable is not initialized and may
  812. * contain old data that is not memory-relevant.
  813. *
  814. * @param p The memory location of the variable
  815. * @param type The datatype description of the variable */
  816. void UA_EXPORT UA_clear(void *p, const UA_DataType *type);
  817. #define UA_deleteMembers(p, type) UA_clear(p, type)
  818. /* Frees a variable and all of its content.
  819. *
  820. * @param p The memory location of the variable
  821. * @param type The datatype description of the variable */
  822. void UA_EXPORT UA_delete(void *p, const UA_DataType *type);
  823. /**
  824. * .. _array-handling:
  825. *
  826. * Array handling
  827. * --------------
  828. * In OPC UA, arrays can have a length of zero or more with the usual meaning.
  829. * In addition, arrays can be undefined. Then, they don't even have a length. In
  830. * the binary encoding, this is indicated by an array of length -1.
  831. *
  832. * In open62541 however, we use ``size_t`` for array lengths. An undefined array
  833. * has length 0 and the data pointer is ``NULL``. An array of length 0 also has
  834. * length 0 but a data pointer ``UA_EMPTY_ARRAY_SENTINEL``. */
  835. /* Allocates and initializes an array of variables of a specific type
  836. *
  837. * @param size The requested array length
  838. * @param type The datatype description
  839. * @return Returns the memory location of the variable or NULL if no memory
  840. could be allocated */
  841. void UA_EXPORT *
  842. UA_Array_new(size_t size, const UA_DataType *type) UA_FUNC_ATTR_MALLOC;
  843. /* Allocates and copies an array
  844. *
  845. * @param src The memory location of the source array
  846. * @param size The size of the array
  847. * @param dst The location of the pointer to the new array
  848. * @param type The datatype of the array members
  849. * @return Returns UA_STATUSCODE_GOOD or UA_STATUSCODE_BADOUTOFMEMORY */
  850. UA_StatusCode UA_EXPORT
  851. UA_Array_copy(const void *src, size_t size, void **dst,
  852. const UA_DataType *type) UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  853. /* Deletes an array.
  854. *
  855. * @param p The memory location of the array
  856. * @param size The size of the array
  857. * @param type The datatype of the array members */
  858. void UA_EXPORT UA_Array_delete(void *p, size_t size, const UA_DataType *type);
  859. /**
  860. * Random Number Generator
  861. * -----------------------
  862. * If UA_MULTITHREADING is defined, then the seed is stored in thread
  863. * local storage. The seed is initialized for every thread in the
  864. * server/client. */
  865. void UA_EXPORT UA_random_seed(UA_UInt64 seed);
  866. UA_UInt32 UA_EXPORT UA_UInt32_random(void); /* no cryptographic entropy */
  867. UA_Guid UA_EXPORT UA_Guid_random(void); /* no cryptographic entropy */
  868. /**
  869. * .. _generated-types:
  870. *
  871. * Generated Data Type Definitions
  872. * -------------------------------
  873. *
  874. * The following data types were auto-generated from a definition in XML format.
  875. */
  876. /* The following is used to exclude type names in the definition of UA_DataType
  877. * structures if the feature is disabled. */
  878. #ifdef UA_ENABLE_TYPEDESCRIPTION
  879. # define UA_TYPENAME(name) name,
  880. #else
  881. # define UA_TYPENAME(name)
  882. #endif
  883. /* Datatype arrays with custom type definitions can be added in a linked list to
  884. * the client or server configuration. Datatype members can point to types in
  885. * the same array via the ``memberTypeIndex``. If ``namespaceZero`` is set to
  886. * true, the member datatype is looked up in the array of builtin datatypes
  887. * instead. */
  888. typedef struct UA_DataTypeArray {
  889. const struct UA_DataTypeArray *next;
  890. const size_t typesSize;
  891. const UA_DataType *types;
  892. } UA_DataTypeArray;
  893. /**
  894. *
  895. * .. toctree::
  896. *
  897. * types_generated */
  898. _UA_END_DECLS
  899. #endif /* UA_TYPES_H_ */