ua_types.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468
  1. /*
  2. * Copyright (C) 2014 the contributors as stated in the AUTHORS file
  3. *
  4. * This file is part of open62541. open62541 is free software: you can
  5. * redistribute it and/or modify it under the terms of the GNU Lesser General
  6. * Public License, version 3 (as published by the Free Software Foundation) with
  7. * a static linking exception as stated in the LICENSE file provided with
  8. * open62541.
  9. *
  10. * open62541 is distributed in the hope that it will be useful, but WITHOUT ANY
  11. * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  12. * A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
  13. * details.
  14. */
  15. #ifndef UA_TYPES_H_
  16. #define UA_TYPES_H_
  17. #ifdef __cplusplus
  18. extern "C" {
  19. #endif
  20. #include <stdint.h>
  21. #ifdef DEBUG
  22. #include <stdio.h>
  23. #endif
  24. #include "ua_config.h"
  25. /**
  26. * @defgroup types Datatypes
  27. *
  28. * @brief This module describes the datatypes used in OPC UA. There is a
  29. * division into built-in datatypes (integers, strings, etc.) and more complex
  30. * datatypes that are comprise of built-in datatypes (structs defined in the OPC
  31. * UA standard).
  32. *
  33. * All datatypes follow the same schema in the naming of relevant functions.
  34. *
  35. * DO NOT CALL THESE FUNCTIONS WITH NULL-POINTERS IF IT IS NOT EXPLICITLY
  36. * PERMITTED.
  37. *
  38. * - <type>_new: Allocates the memory for the type and runs <type>_init on the
  39. * returned variable. Returns null if no memory could be allocated.
  40. *
  41. * - <type>_init: Sets all members to a "safe" standard, usually zero. Arrays
  42. * (e.g. for strings) are set to a length of -1.
  43. *
  44. * - <type>_copy: Copies a datatype. This performs a deep copy that iterates
  45. * over the members. Copying into variants with an external data source is
  46. * not permitted. If copying fails, a deleteMembers is performed and an error
  47. * code returned.
  48. *
  49. * - <type>_delete: Frees the memory where the datatype was stored. This
  50. * performs an _deleteMembers internally if required.
  51. *
  52. * - <type>_deleteMembers: Frees the memory of dynamically sized members (e.g. a
  53. * string) of a datatype. This is useful when the datatype was allocated on
  54. * the stack, whereas the dynamically sized members is heap-allocated. To
  55. * reuse the variable, the remaining members (not dynamically allocated) need
  56. * to be cleaned up with an _init.
  57. */
  58. /** @brief A two-state logical value (true or false). */
  59. typedef _Bool UA_Boolean;
  60. /** @brief An integer value between -129 and 127. */
  61. typedef int8_t UA_SByte;
  62. #define UA_SBYTE_MAX -128
  63. #define UA_SBYTE_MIN 127
  64. /** @brief An integer value between 0 and 256. */
  65. typedef uint8_t UA_Byte;
  66. #define UA_BYTE_MAX 256
  67. #define UA_BYTE_MIN 0
  68. /** @brief An integer value between -32 768 and 32 767. */
  69. typedef int16_t UA_Int16;
  70. #define UA_INT16_MAX 32767
  71. #define UA_INT16_MIN -32768
  72. /** @brief An integer value between 0 and 65 535. */
  73. typedef uint16_t UA_UInt16;
  74. #define UA_UINT16_MAX 65535
  75. #define UA_UINT16_MIN 0
  76. /** @brief An integer value between -2 147 483 648 and 2 147 483 647. */
  77. typedef int32_t UA_Int32;
  78. #define UA_INT32_MAX 2147483647
  79. #define UA_INT32_MIN −2147483648
  80. /** @brief An integer value between 0 and 429 4967 295. */
  81. typedef uint32_t UA_UInt32;
  82. #define UA_UINT32_MAX 4294967295
  83. #define UA_UINT32_MIN 0
  84. /** @brief An integer value between -10 223 372 036 854 775 808 and 9 223 372 036 854 775 807 */
  85. typedef int64_t UA_Int64;
  86. #define UA_INT64_MAX 9223372036854775807
  87. #define UA_INT64_MIN −9223372036854775808
  88. /** @brief An integer value between 0 and 18 446 744 073 709 551 615. */
  89. typedef uint64_t UA_UInt64;
  90. #define UA_UINT64_MAX = 18446744073709551615
  91. #define UA_UINT64_MIN = 0
  92. /** @brief An IEEE single precision (32 bit) floating point value. */
  93. typedef float UA_Float;
  94. /** @brief An IEEE double precision (64 bit) floating point value. */
  95. typedef double UA_Double;
  96. /** @brief A sequence of Unicode characters. */
  97. typedef struct UA_String {
  98. UA_Int32 length;
  99. UA_Byte *data;
  100. } UA_String;
  101. /** @brief An instance in time. */
  102. typedef UA_Int64 UA_DateTime; //100 nanosecond resolution
  103. /** @brief A 16 byte value that can be used as a globally unique identifier. */
  104. typedef struct UA_Guid {
  105. UA_UInt32 data1;
  106. UA_UInt16 data2;
  107. UA_UInt16 data3;
  108. UA_Byte data4[8];
  109. } UA_Guid;
  110. /** @brief A sequence of octets. */
  111. typedef struct UA_String UA_ByteString;
  112. /** @brief An XML element. */
  113. typedef struct UA_String UA_XmlElement;
  114. /** @brief An identifier for a node in the address space of an OPC UA Server. */
  115. /* The shortened numeric types are introduced during encoding. */
  116. typedef struct UA_NodeId {
  117. UA_UInt16 namespaceIndex;
  118. enum {
  119. UA_NODEIDTYPE_NUMERIC = 2,
  120. UA_NODEIDTYPE_STRING = 3,
  121. UA_NODEIDTYPE_GUID = 4,
  122. UA_NODEIDTYPE_BYTESTRING = 5
  123. } identifierType;
  124. union {
  125. UA_UInt32 numeric;
  126. UA_String string;
  127. UA_Guid guid;
  128. UA_ByteString byteString;
  129. } identifier;
  130. } UA_NodeId;
  131. /** @brief A NodeId that allows the namespace URI to be specified instead of an index. */
  132. typedef struct UA_ExpandedNodeId {
  133. UA_NodeId nodeId;
  134. UA_String namespaceUri; // not encoded if length=-1
  135. UA_UInt32 serverIndex; // not encoded if 0
  136. } UA_ExpandedNodeId;
  137. #include "ua_statuscodes.h"
  138. /** @brief A numeric identifier for a error or condition that is associated with a value or an operation. */
  139. typedef enum UA_StatusCode UA_StatusCode; // StatusCodes aren't an enum(=int) since 32 unsigned bits are needed. See also ua_statuscodes.h */
  140. /** @brief A name qualified by a namespace. */
  141. typedef struct UA_QualifiedName {
  142. UA_UInt16 namespaceIndex;
  143. UA_String name;
  144. } UA_QualifiedName;
  145. /** @brief Human readable text with an optional locale identifier. */
  146. typedef struct UA_LocalizedText {
  147. UA_String locale;
  148. UA_String text;
  149. } UA_LocalizedText;
  150. /** @brief A structure that contains an application specific data type that may
  151. not be recognized by the receiver. */
  152. typedef struct UA_ExtensionObject {
  153. UA_NodeId typeId;
  154. enum {
  155. UA_EXTENSIONOBJECT_ENCODINGMASK_NOBODYISENCODED = 0,
  156. UA_EXTENSIONOBJECT_ENCODINGMASK_BODYISBYTESTRING = 1,
  157. UA_EXTENSIONOBJECT_ENCODINGMASK_BODYISXML = 2
  158. } encoding;
  159. UA_ByteString body; // contains either the bytestring or a pointer to the memory-object
  160. } UA_ExtensionObject;
  161. struct UA_VTable_Entry; // forwards declaration
  162. typedef struct UA_VTable_Entry UA_VTable_Entry;
  163. /* Variant */
  164. /** @defgroup variant Variant
  165. *
  166. * @brief Variants may contain (arrays of) any other datatype.
  167. *
  168. * For that, we provide a reference to the utility functions of the type as well
  169. * as possible encoding by pointing an entry in the vtable of types. References
  170. * may either contain a structure with the variants data, or a datasource where
  171. * this structure may be obtained (using reference counting for async access).
  172. *
  173. * @{
  174. */
  175. typedef struct UA_VariantData {
  176. UA_Int32 arrayLength; // total number of elements in the data-pointer
  177. void *dataPtr;
  178. UA_Int32 arrayDimensionsLength;
  179. UA_Int32 *arrayDimensions;
  180. } UA_VariantData;
  181. /** @brief A datasource is the interface to interact with a local data provider.
  182. *
  183. * Implementors of datasources need to provide functions for the callbacks in
  184. * this structure. As a rule, datasources are never copied, but only their
  185. * content. The only way to write into a datasource is via the write-service. */
  186. typedef struct UA_VariantDataSource {
  187. const void *identifier; /**< whatever id the datasource uses internally. Can be ignored if the datasource functions do not use it. */
  188. UA_Int32 (*read)(const void *identifier, const UA_VariantData **); /**< Get the current data from the datasource. When it is no longer used, the data has to be relased. */
  189. void (*release)(const void *identifier, const UA_VariantData *); /**< For concurrent access, the datasource needs to know when the last reader releases replaced/deleted data. Release decreases the reference count. */
  190. UA_Int32 (*write)(const void **identifier, const UA_VariantData *); /**< Replace the data in the datasource. Also used to replace the identifier pointer for lookups. Do not free the variantdata afterwards! */
  191. void (*delete)(const void *identifier); /**< Indicates that the node with the datasource was removed from the namespace. */
  192. } UA_VariantDataSource;
  193. /** @brief A union of all of the types specified above.
  194. *
  195. * Variants store (arrays of) built-in types. If you want to store a more
  196. * complex (or self-defined) type, you have to use an UA_ExtensionObject.*/
  197. typedef struct UA_Variant {
  198. const UA_VTable_Entry *vt; // internal entry into vTable
  199. enum {
  200. UA_VARIANT_DATA,
  201. UA_VARIANT_DATA_NODELETE, // do not free the data (e.g. because it is "borrowed" and points into a larger structure)
  202. UA_VARIANT_DATASOURCE
  203. } storageType;
  204. union {
  205. UA_VariantData data;
  206. UA_VariantDataSource datasource;
  207. } storage;
  208. } UA_Variant;
  209. /** @} */
  210. /** @brief A data value with an associated status code and timestamps. */
  211. typedef struct UA_DataValue {
  212. UA_Byte encodingMask;
  213. UA_Variant value;
  214. UA_StatusCode status;
  215. UA_DateTime sourceTimestamp;
  216. UA_Int16 sourcePicoseconds;
  217. UA_DateTime serverTimestamp;
  218. UA_Int16 serverPicoseconds;
  219. } UA_DataValue;
  220. enum UA_DATAVALUE_ENCODINGMASKTYPE_enum {
  221. UA_DATAVALUE_ENCODINGMASK_VARIANT = 0x01,
  222. UA_DATAVALUE_ENCODINGMASK_STATUSCODE = 0x02,
  223. UA_DATAVALUE_ENCODINGMASK_SOURCETIMESTAMP = 0x04,
  224. UA_DATAVALUE_ENCODINGMASK_SERVERTIMESTAMP = 0x08,
  225. UA_DATAVALUE_ENCODINGMASK_SOURCEPICOSECONDS = 0x10,
  226. UA_DATAVALUE_ENCODINGMASK_SERVERPICOSECONDS = 0x20
  227. };
  228. /** @brief A structure that contains detailed error and diagnostic information associated with a StatusCode. */
  229. typedef struct UA_DiagnosticInfo {
  230. UA_Byte encodingMask; // Type of the Enum UA_DIAGNOSTICINFO_ENCODINGMASKTYPE
  231. UA_Int32 symbolicId;
  232. UA_Int32 namespaceUri;
  233. UA_Int32 localizedText;
  234. UA_Int32 locale;
  235. UA_String additionalInfo;
  236. UA_StatusCode innerStatusCode;
  237. struct UA_DiagnosticInfo *innerDiagnosticInfo;
  238. } UA_DiagnosticInfo;
  239. enum UA_DIAGNOSTICINFO_ENCODINGMASKTYPE_enum {
  240. UA_DIAGNOSTICINFO_ENCODINGMASK_SYMBOLICID = 0x01,
  241. UA_DIAGNOSTICINFO_ENCODINGMASK_NAMESPACE = 0x02,
  242. UA_DIAGNOSTICINFO_ENCODINGMASK_LOCALIZEDTEXT = 0x04,
  243. UA_DIAGNOSTICINFO_ENCODINGMASK_LOCALE = 0x08,
  244. UA_DIAGNOSTICINFO_ENCODINGMASK_ADDITIONALINFO = 0x10,
  245. UA_DIAGNOSTICINFO_ENCODINGMASK_INNERSTATUSCODE = 0x20,
  246. UA_DIAGNOSTICINFO_ENCODINGMASK_INNERDIAGNOSTICINFO = 0x40
  247. };
  248. /** @brief Type use internally to denote an invalid datatype. */
  249. typedef void UA_InvalidType;
  250. /*************/
  251. /* Functions */
  252. /*************/
  253. #ifdef DEBUG
  254. #define PRINTTYPE(TYPE) void UA_EXPORT TYPE##_print(const TYPE *p, FILE *stream);
  255. #define PRINTTYPE_NOEXPORT(TYPE) void TYPE##_print(const TYPE *p, FILE *stream);
  256. #else
  257. #define PRINTTYPE(TYPE)
  258. #define PRINTTYPE_NOEXPORT(TYPE)
  259. #endif
  260. #define UA_TYPE_PROTOTYPES(TYPE) \
  261. TYPE UA_EXPORT * TYPE##_new(); \
  262. void UA_EXPORT TYPE##_init(TYPE * p); \
  263. void UA_EXPORT TYPE##_delete(TYPE * p); \
  264. void UA_EXPORT TYPE##_deleteMembers(TYPE * p); \
  265. UA_StatusCode UA_EXPORT TYPE##_copy(const TYPE *src, TYPE *dst); \
  266. PRINTTYPE(TYPE)
  267. #define UA_TYPE_PROTOTYPES_NOEXPORT(TYPE) \
  268. TYPE * TYPE##_new(); \
  269. void TYPE##_init(TYPE * p); \
  270. void TYPE##_delete(TYPE * p); \
  271. void TYPE##_deleteMembers(TYPE * p); \
  272. UA_StatusCode TYPE##_copy(const TYPE *src, TYPE *dst); \
  273. PRINTTYPE_NOEXPORT(TYPE)
  274. /* Functions for all types */
  275. UA_TYPE_PROTOTYPES(UA_Boolean)
  276. UA_TYPE_PROTOTYPES(UA_SByte)
  277. UA_TYPE_PROTOTYPES(UA_Byte)
  278. UA_TYPE_PROTOTYPES(UA_Int16)
  279. UA_TYPE_PROTOTYPES(UA_UInt16)
  280. UA_TYPE_PROTOTYPES(UA_Int32)
  281. UA_TYPE_PROTOTYPES(UA_UInt32)
  282. UA_TYPE_PROTOTYPES(UA_Int64)
  283. UA_TYPE_PROTOTYPES(UA_UInt64)
  284. UA_TYPE_PROTOTYPES(UA_Float)
  285. UA_TYPE_PROTOTYPES(UA_Double)
  286. UA_TYPE_PROTOTYPES(UA_String)
  287. UA_TYPE_PROTOTYPES(UA_DateTime)
  288. UA_TYPE_PROTOTYPES(UA_Guid)
  289. UA_TYPE_PROTOTYPES(UA_ByteString)
  290. UA_TYPE_PROTOTYPES(UA_XmlElement)
  291. UA_TYPE_PROTOTYPES(UA_NodeId)
  292. UA_TYPE_PROTOTYPES(UA_ExpandedNodeId)
  293. UA_TYPE_PROTOTYPES(UA_StatusCode)
  294. UA_TYPE_PROTOTYPES(UA_QualifiedName)
  295. UA_TYPE_PROTOTYPES(UA_LocalizedText)
  296. UA_TYPE_PROTOTYPES(UA_ExtensionObject)
  297. UA_TYPE_PROTOTYPES(UA_DataValue)
  298. UA_TYPE_PROTOTYPES(UA_Variant)
  299. UA_TYPE_PROTOTYPES(UA_DiagnosticInfo)
  300. UA_TYPE_PROTOTYPES(UA_InvalidType)
  301. /**********************************************/
  302. /* Custom functions for the builtin datatypes */
  303. /**********************************************/
  304. /* String */
  305. #define UA_STRING_NULL (UA_String) {-1, (UA_Byte*)0 }
  306. #define UA_STRING_STATIC(VARIABLE, STRING) do { \
  307. VARIABLE.length = sizeof(STRING)-1; \
  308. VARIABLE.data = (UA_Byte *)STRING; } while(0)
  309. UA_StatusCode UA_EXPORT UA_String_copycstring(char const *src, UA_String *dst);
  310. UA_StatusCode UA_EXPORT UA_String_copyprintf(char const *fmt, UA_String *dst, ...);
  311. UA_Boolean UA_EXPORT UA_String_equal(const UA_String *string1, const UA_String *string2);
  312. #ifdef DEBUG
  313. void UA_EXPORT UA_String_printf(char const *label, const UA_String *string);
  314. void UA_EXPORT UA_String_printx(char const *label, const UA_String *string);
  315. void UA_EXPORT UA_String_printx_hex(char const *label, const UA_String *string);
  316. #endif
  317. /* DateTime */
  318. UA_DateTime UA_EXPORT UA_DateTime_now();
  319. typedef struct UA_DateTimeStruct {
  320. UA_Int16 nanoSec;
  321. UA_Int16 microSec;
  322. UA_Int16 milliSec;
  323. UA_Int16 sec;
  324. UA_Int16 min;
  325. UA_Int16 hour;
  326. UA_Int16 day;
  327. UA_Int16 mounth;
  328. UA_Int16 year;
  329. } UA_DateTimeStruct;
  330. UA_DateTimeStruct UA_EXPORT UA_DateTime_toStruct(UA_DateTime time);
  331. UA_StatusCode UA_EXPORT UA_DateTime_toString(UA_DateTime time, UA_String *timeString);
  332. /* Guid */
  333. UA_Boolean UA_EXPORT UA_Guid_equal(const UA_Guid *g1, const UA_Guid *g2);
  334. /* ByteString */
  335. UA_Boolean UA_EXPORT UA_ByteString_equal(const UA_ByteString *string1, const UA_ByteString *string2);
  336. UA_StatusCode UA_EXPORT UA_ByteString_newMembers(UA_ByteString *p, UA_Int32 length);
  337. #ifdef DEBUG
  338. void UA_EXPORT UA_ByteString_printf(char *label, const UA_ByteString *string);
  339. void UA_EXPORT UA_ByteString_printx(char *label, const UA_ByteString *string);
  340. void UA_EXPORT UA_ByteString_printx_hex(char *label, const UA_ByteString *string);
  341. #endif
  342. /* NodeId */
  343. UA_Boolean UA_EXPORT UA_NodeId_equal(const UA_NodeId *n1, const UA_NodeId *n2);
  344. UA_Boolean UA_EXPORT UA_NodeId_isNull(const UA_NodeId *p);
  345. /* ExpandedNodeId */
  346. UA_Boolean UA_EXPORT UA_ExpandedNodeId_isNull(const UA_ExpandedNodeId *p);
  347. /* QualifiedName */
  348. #define UA_QUALIFIEDNAME_STATIC(VARIABLE, STRING) do { \
  349. VARIABLE.namespaceIndex = 0; \
  350. UA_STRING_STATIC(VARIABLE.name, STRING); } while(0)
  351. UA_StatusCode UA_EXPORT UA_QualifiedName_copycstring(char const *src, UA_QualifiedName *dst);
  352. #ifdef DEBUG
  353. void UA_EXPORT UA_QualifiedName_printf(char const *label, const UA_QualifiedName *qn);
  354. #endif
  355. /* LocalizedText */
  356. #define UA_LOCALIZEDTEXT_STATIC(VARIABLE, STRING) do { \
  357. UA_STRING_STATIC(VARIABLE.locale, "en"); \
  358. UA_STRING_STATIC(VARIABLE.text, STRING); } while(0)
  359. UA_StatusCode UA_EXPORT UA_LocalizedText_copycstring(char const *src, UA_LocalizedText *dst);
  360. /* Variant */
  361. UA_StatusCode UA_EXPORT UA_Variant_copySetValue(UA_Variant *v, const UA_VTable_Entry *vt, const void *value);
  362. UA_StatusCode UA_EXPORT UA_Variant_copySetArray(UA_Variant *v, const UA_VTable_Entry *vt, UA_Int32 arrayLength, const void *array);
  363. /* Array operations */
  364. UA_StatusCode UA_EXPORT UA_Array_new(void **p, UA_Int32 noElements, const UA_VTable_Entry *vt);
  365. void UA_EXPORT UA_Array_init(void *p, UA_Int32 noElements, const UA_VTable_Entry *vt);
  366. void UA_EXPORT UA_Array_delete(void *p, UA_Int32 noElements, const UA_VTable_Entry *vt);
  367. /* @brief The destination array is allocated with size noElements. */
  368. UA_StatusCode UA_EXPORT UA_Array_copy(const void *src, UA_Int32 noElements, const UA_VTable_Entry *vt, void **dst);
  369. #ifdef DEBUG
  370. void UA_EXPORT UA_Array_print(const void *p, UA_Int32 noElements, const UA_VTable_Entry *vt, FILE *stream);
  371. #endif
  372. /**********/
  373. /* VTable */
  374. /**********/
  375. typedef struct UA_Encoding {
  376. /** Returns the size of the encoded element.*/
  377. UA_Int32 (*calcSize)(const void *p);
  378. /** Encodes the type into the destination bytestring. */
  379. UA_StatusCode (*encode)(const void *src, UA_ByteString *dst, UA_UInt32 *offset);
  380. /** Decodes a ByteString into an UA datatype. */
  381. UA_StatusCode (*decode)(const UA_ByteString *src, UA_UInt32 *offset, void *dst);
  382. } UA_Encoding;
  383. #define UA_ENCODING_BINARY 0 // Binary encoding is always available
  384. struct UA_VTable_Entry {
  385. UA_NodeId typeId;
  386. UA_Byte *name;
  387. void * (*new)();
  388. void (*init)(void *p);
  389. UA_StatusCode (*copy)(void const *src, void *dst);
  390. void (*delete)(void *p);
  391. void (*deleteMembers)(void *p);
  392. #ifdef DEBUG
  393. void (*print)(const void *p, FILE *stream);
  394. #endif
  395. UA_UInt32 memSize; // size of the struct only in memory (no dynamic components)
  396. UA_Boolean dynMembers; // does the type contain members that are dynamically
  397. // allocated (strings, ..)? Otherwise, the size on
  398. // the wire == size in memory.
  399. UA_Encoding encodings[UA_ENCODING_AMOUNT]; // binary, xml, ... UA_ENCODING_AMOUNT is set by the build script
  400. };
  401. #ifdef __cplusplus
  402. } // extern "C"
  403. #endif
  404. #endif /* UA_TYPES_H_ */