ua_server.h 33 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743
  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_SERVER_H_
  16. #define UA_SERVER_H_
  17. #ifdef __cplusplus
  18. extern "C" {
  19. #endif
  20. #include "ua_config.h"
  21. #include "ua_types.h"
  22. #include "ua_types_generated.h"
  23. #include "ua_nodeids.h"
  24. #include "ua_log.h"
  25. #include "ua_job.h"
  26. #include "ua_connection.h"
  27. /**
  28. * Server
  29. * ======
  30. *
  31. * Network Layer
  32. * -------------
  33. * Interface to the binary network layers. The functions in the network layer
  34. * are never called in parallel but only sequentially from the server's main
  35. * loop. So the network layer does not need to be thread-safe. */
  36. struct UA_ServerNetworkLayer;
  37. typedef struct UA_ServerNetworkLayer UA_ServerNetworkLayer;
  38. struct UA_ServerNetworkLayer {
  39. void *handle; // pointer to internal data
  40. UA_String discoveryUrl;
  41. /* Starts listening on the the networklayer.
  42. *
  43. * @param nl The network layer
  44. * @param logger The logger
  45. * @return Returns UA_STATUSCODE_GOOD or an error code. */
  46. UA_StatusCode (*start)(UA_ServerNetworkLayer *nl, UA_Logger logger);
  47. /* Gets called from the main server loop and returns the jobs (accumulated
  48. * messages and close events) for dispatch.
  49. *
  50. * @param nl The network layer
  51. * @param jobs When the returned integer is >0, *jobs points to an array of UA_Job of the
  52. * returned size.
  53. * @param timeout The timeout during which an event must arrive in microseconds
  54. * @return The size of the jobs array. If the result is negative, an error has occurred. */
  55. size_t (*getJobs)(UA_ServerNetworkLayer *nl, UA_Job **jobs, UA_UInt16 timeout);
  56. /* Closes the network connection and returns all the jobs that need to be
  57. * finished before the network layer can be safely deleted.
  58. *
  59. * @param nl The network layer
  60. * @param jobs When the returned integer is >0, jobs points to an array of UA_Job of the
  61. * returned size.
  62. * @return The size of the jobs array. If the result is negative, an error has occurred. */
  63. size_t (*stop)(UA_ServerNetworkLayer *nl, UA_Job **jobs);
  64. /** Deletes the network content. Call only after stopping. */
  65. void (*deleteMembers)(UA_ServerNetworkLayer *nl);
  66. };
  67. /**
  68. * Server Configuration
  69. * --------------------
  70. * The following structure is passed to a new server for configuration. */
  71. typedef struct {
  72. UA_String username;
  73. UA_String password;
  74. } UA_UsernamePasswordLogin;
  75. typedef struct {
  76. UA_UInt32 min;
  77. UA_UInt32 max;
  78. } UA_UInt32Range;
  79. typedef struct {
  80. UA_Double min;
  81. UA_Double max;
  82. } UA_DoubleRange;
  83. typedef struct {
  84. UA_UInt16 nThreads; /* only if multithreading is enabled */
  85. UA_Logger logger;
  86. /* Server Description */
  87. UA_BuildInfo buildInfo;
  88. UA_ApplicationDescription applicationDescription;
  89. UA_ByteString serverCertificate;
  90. /* Networking */
  91. size_t networkLayersSize;
  92. UA_ServerNetworkLayer *networkLayers;
  93. /* Login */
  94. UA_Boolean enableAnonymousLogin;
  95. UA_Boolean enableUsernamePasswordLogin;
  96. size_t usernamePasswordLoginsSize;
  97. UA_UsernamePasswordLogin* usernamePasswordLogins;
  98. /* Limits for SecureChannels */
  99. UA_UInt16 maxSecureChannels;
  100. UA_UInt32 maxSecurityTokenLifetime; /* in ms */
  101. /* Limits for Sessions */
  102. UA_UInt16 maxSessions;
  103. UA_Double maxSessionTimeout; /* in ms */
  104. /* Limits for Subscriptions */
  105. UA_DoubleRange publishingIntervalLimits;
  106. UA_UInt32Range lifeTimeCountLimits;
  107. UA_UInt32Range keepAliveCountLimits;
  108. UA_UInt32 maxNotificationsPerPublish;
  109. /* Limits for MonitoredItems */
  110. UA_DoubleRange samplingIntervalLimits;
  111. UA_UInt32Range queueSizeLimits;
  112. } UA_ServerConfig;
  113. /**
  114. * Server Lifecycle
  115. * ---------------- */
  116. UA_Server UA_EXPORT * UA_Server_new(const UA_ServerConfig config);
  117. void UA_EXPORT UA_Server_delete(UA_Server *server);
  118. /* Runs the main loop of the server. In each iteration, this calls into the
  119. * networklayers to see if jobs have arrived and checks if repeated jobs need to
  120. * be triggered.
  121. *
  122. * @param server The server object.
  123. * @param running The loop is run as long as *running is true. Otherwise, the server shuts down.
  124. * @return Returns the statuscode of the UA_Server_run_shutdown method */
  125. UA_StatusCode UA_EXPORT UA_Server_run(UA_Server *server, volatile UA_Boolean *running);
  126. /* The prologue part of UA_Server_run (no need to use if you call UA_Server_run) */
  127. UA_StatusCode UA_EXPORT UA_Server_run_startup(UA_Server *server);
  128. /* Executes a single iteration of the server's main loop.
  129. *
  130. * @param server The server object.
  131. * @param waitInternal Should we wait for messages in the networklayer?
  132. * Otherwise, the timouts for the networklayers are set to zero.
  133. * The default max wait time is 50millisec.
  134. * @return Returns how long we can wait until the next scheduled job (in millisec) */
  135. UA_UInt16 UA_EXPORT UA_Server_run_iterate(UA_Server *server, UA_Boolean waitInternal);
  136. /* The epilogue part of UA_Server_run (no need to use if you call UA_Server_run) */
  137. UA_StatusCode UA_EXPORT UA_Server_run_shutdown(UA_Server *server);
  138. /**
  139. * Modify a running server
  140. * ----------------------- */
  141. /* Add a job for cyclic repetition to the server.
  142. *
  143. * @param server The server object.
  144. * @param job The job that shall be added.
  145. * @param interval The job shall be repeatedly executed with the given interval
  146. * (in ms). The interval must be larger than 5ms. The first execution
  147. * occurs at now() + interval at the latest.
  148. * @param jobId Set to the guid of the repeated job. This can be used to cancel
  149. * the job later on. If the pointer is null, the guid is not set.
  150. * @return Upon success, UA_STATUSCODE_GOOD is returned. An error code otherwise. */
  151. UA_StatusCode UA_EXPORT UA_Server_addRepeatedJob(UA_Server *server, UA_Job job,
  152. UA_UInt32 interval, UA_Guid *jobId);
  153. /* Remove repeated job. The entry will be removed asynchronously during the next
  154. * iteration of the server main loop.
  155. *
  156. * @param server The server object.
  157. * @param jobId The id of the job that shall be removed.
  158. * @return Upon sucess, UA_STATUSCODE_GOOD is returned. An error code otherwise. */
  159. UA_StatusCode UA_EXPORT UA_Server_removeRepeatedJob(UA_Server *server, UA_Guid jobId);
  160. /* Add a new namespace to the server. Returns the index of the new namespace */
  161. UA_UInt16 UA_EXPORT UA_Server_addNamespace(UA_Server *server, const char* name);
  162. /**
  163. * Reading / Writing Node Attributes
  164. * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  165. *
  166. * The node attributes are read/written separately. The read/write functions do
  167. * not require the construction of variants used in the service definition. This
  168. * is handled internally.
  169. *
  170. * Reading Node Attributes
  171. * ~~~~~~~~~~~~~~~~~~~~~~~
  172. *
  173. * The following attributes cannot be read, since the local "admin" user always has
  174. * full rights.
  175. *
  176. * - UserWriteMask
  177. * - UserAccessLevel
  178. * - UserExecutable */
  179. /* Don't use this function. There are typed versions for every supported attribute. */
  180. UA_StatusCode UA_EXPORT
  181. __UA_Server_read(UA_Server *server, const UA_NodeId *nodeId,
  182. UA_AttributeId attributeId, void *v);
  183. static UA_INLINE UA_StatusCode
  184. UA_Server_readNodeId(UA_Server *server, const UA_NodeId nodeId,
  185. UA_NodeId *outNodeId) {
  186. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_NODEID, outNodeId); }
  187. static UA_INLINE UA_StatusCode
  188. UA_Server_readNodeClass(UA_Server *server, const UA_NodeId nodeId,
  189. UA_NodeClass *outNodeClass) {
  190. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_NODECLASS, outNodeClass); }
  191. static UA_INLINE UA_StatusCode
  192. UA_Server_readBrowseName(UA_Server *server, const UA_NodeId nodeId,
  193. UA_QualifiedName *outBrowseName) {
  194. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_BROWSENAME, outBrowseName); }
  195. static UA_INLINE UA_StatusCode
  196. UA_Server_readDisplayName(UA_Server *server, const UA_NodeId nodeId,
  197. UA_LocalizedText *outDisplayName) {
  198. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_DISPLAYNAME, outDisplayName); }
  199. static UA_INLINE UA_StatusCode
  200. UA_Server_readDescription(UA_Server *server, const UA_NodeId nodeId,
  201. UA_LocalizedText *outDescription) {
  202. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_DESCRIPTION, outDescription); }
  203. static UA_INLINE UA_StatusCode
  204. UA_Server_readWriteMask(UA_Server *server, const UA_NodeId nodeId,
  205. UA_UInt32 *outWriteMask) {
  206. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_WRITEMASK, outWriteMask); }
  207. static UA_INLINE UA_StatusCode
  208. UA_Server_readIsAbstract(UA_Server *server, const UA_NodeId nodeId,
  209. UA_Boolean *outIsAbstract) {
  210. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_ISABSTRACT, outIsAbstract); }
  211. static UA_INLINE UA_StatusCode
  212. UA_Server_readSymmetric(UA_Server *server, const UA_NodeId nodeId,
  213. UA_Boolean *outSymmetric) {
  214. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_SYMMETRIC, outSymmetric); }
  215. static UA_INLINE UA_StatusCode
  216. UA_Server_readInverseName(UA_Server *server, const UA_NodeId nodeId,
  217. UA_LocalizedText *outInverseName) {
  218. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_INVERSENAME, outInverseName); }
  219. static UA_INLINE UA_StatusCode
  220. UA_Server_readContainsNoLoop(UA_Server *server, const UA_NodeId nodeId,
  221. UA_Boolean *outContainsNoLoops) {
  222. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_CONTAINSNOLOOPS,
  223. outContainsNoLoops); }
  224. static UA_INLINE UA_StatusCode
  225. UA_Server_readEventNotifier(UA_Server *server, const UA_NodeId nodeId,
  226. UA_Byte *outEventNotifier) {
  227. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_EVENTNOTIFIER, outEventNotifier); }
  228. static UA_INLINE UA_StatusCode
  229. UA_Server_readValue(UA_Server *server, const UA_NodeId nodeId,
  230. UA_Variant *outValue) {
  231. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_VALUE, outValue); }
  232. static UA_INLINE UA_StatusCode
  233. UA_Server_readDataType(UA_Server *server, const UA_NodeId nodeId,
  234. UA_NodeId *outDataType) {
  235. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_DATATYPE, outDataType); }
  236. static UA_INLINE UA_StatusCode
  237. UA_Server_readValueRank(UA_Server *server, const UA_NodeId nodeId,
  238. UA_Int32 *outValueRank) {
  239. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_VALUERANK, outValueRank); }
  240. /* Returns a variant with an int32 array */
  241. static UA_INLINE UA_StatusCode
  242. UA_Server_readArrayDimensions(UA_Server *server, const UA_NodeId nodeId,
  243. UA_Variant *outArrayDimensions) {
  244. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_ARRAYDIMENSIONS,
  245. outArrayDimensions); }
  246. static UA_INLINE UA_StatusCode
  247. UA_Server_readAccessLevel(UA_Server *server, const UA_NodeId nodeId,
  248. UA_UInt32 *outAccessLevel) {
  249. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_ACCESSLEVEL, outAccessLevel); }
  250. static UA_INLINE UA_StatusCode
  251. UA_Server_readMinimumSamplingInterval(UA_Server *server, const UA_NodeId nodeId,
  252. UA_Double *outMinimumSamplingInterval) {
  253. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_MINIMUMSAMPLINGINTERVAL,
  254. outMinimumSamplingInterval); }
  255. static UA_INLINE UA_StatusCode
  256. UA_Server_readHistorizing(UA_Server *server, const UA_NodeId nodeId,
  257. UA_Boolean *outHistorizing) {
  258. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_HISTORIZING, outHistorizing); }
  259. static UA_INLINE UA_StatusCode
  260. UA_Server_readExecutable(UA_Server *server, const UA_NodeId nodeId,
  261. UA_Boolean *outExecutable) {
  262. return __UA_Server_read(server, &nodeId, UA_ATTRIBUTEID_EXECUTABLE, outExecutable); }
  263. /**
  264. * Writing Node Attributes
  265. * ~~~~~~~~~~~~~~~~~~~~~~~
  266. *
  267. * The following node attributes cannot be changed once a node has been created:
  268. *
  269. * - NodeClass
  270. * - NodeId
  271. * - Symmetric
  272. * - ContainsNoLoop
  273. *
  274. * The following attributes cannot be written from the server, as they are
  275. * specific to the different users:
  276. *
  277. * - UserWriteMask
  278. * - UserAccessLevel
  279. * - UserExecutable
  280. *
  281. * The following attributes are currently taken from the value variant and not
  282. * stored separately in the nodes:
  283. *
  284. * - DataType
  285. * - ValueRank
  286. * - ArrayDimensions
  287. *
  288. * Historizing is currently unsupported */
  289. /* Don't use this function. There are typed versions with no additional overhead. */
  290. UA_StatusCode UA_EXPORT
  291. __UA_Server_write(UA_Server *server, const UA_NodeId *nodeId,
  292. const UA_AttributeId attributeId,
  293. const UA_DataType *type, const void *value);
  294. static UA_INLINE UA_StatusCode
  295. UA_Server_writeBrowseName(UA_Server *server, const UA_NodeId nodeId,
  296. const UA_QualifiedName browseName) {
  297. return __UA_Server_write(server, &nodeId, UA_ATTRIBUTEID_BROWSENAME,
  298. &UA_TYPES[UA_TYPES_QUALIFIEDNAME], &browseName); }
  299. static UA_INLINE UA_StatusCode
  300. UA_Server_writeDisplayName(UA_Server *server, const UA_NodeId nodeId,
  301. const UA_LocalizedText displayName) {
  302. return __UA_Server_write(server, &nodeId, UA_ATTRIBUTEID_DISPLAYNAME,
  303. &UA_TYPES[UA_TYPES_LOCALIZEDTEXT], &displayName); }
  304. static UA_INLINE UA_StatusCode
  305. UA_Server_writeDescription(UA_Server *server, const UA_NodeId nodeId,
  306. const UA_LocalizedText description) {
  307. return __UA_Server_write(server, &nodeId, UA_ATTRIBUTEID_DESCRIPTION,
  308. &UA_TYPES[UA_TYPES_LOCALIZEDTEXT], &description); }
  309. static UA_INLINE UA_StatusCode
  310. UA_Server_writeWriteMask(UA_Server *server, const UA_NodeId nodeId,
  311. const UA_UInt32 writeMask) {
  312. return __UA_Server_write(server, &nodeId, UA_ATTRIBUTEID_WRITEMASK,
  313. &UA_TYPES[UA_TYPES_UINT32], &writeMask); }
  314. static UA_INLINE UA_StatusCode
  315. UA_Server_writeIsAbstract(UA_Server *server, const UA_NodeId nodeId,
  316. const UA_Boolean isAbstract) {
  317. return __UA_Server_write(server, &nodeId, UA_ATTRIBUTEID_ISABSTRACT,
  318. &UA_TYPES[UA_TYPES_BOOLEAN], &isAbstract); }
  319. static UA_INLINE UA_StatusCode
  320. UA_Server_writeInverseName(UA_Server *server, const UA_NodeId nodeId,
  321. const UA_LocalizedText inverseName) {
  322. return __UA_Server_write(server, &nodeId, UA_ATTRIBUTEID_INVERSENAME,
  323. &UA_TYPES[UA_TYPES_LOCALIZEDTEXT], &inverseName); }
  324. static UA_INLINE UA_StatusCode
  325. UA_Server_writeEventNotifier(UA_Server *server, const UA_NodeId nodeId,
  326. const UA_Byte eventNotifier) {
  327. return __UA_Server_write(server, &nodeId, UA_ATTRIBUTEID_EVENTNOTIFIER,
  328. &UA_TYPES[UA_TYPES_BYTE], &eventNotifier); }
  329. static UA_INLINE UA_StatusCode
  330. UA_Server_writeValue(UA_Server *server, const UA_NodeId nodeId,
  331. const UA_Variant value) {
  332. return __UA_Server_write(server, &nodeId, UA_ATTRIBUTEID_VALUE,
  333. &UA_TYPES[UA_TYPES_VARIANT], &value); }
  334. static UA_INLINE UA_StatusCode
  335. UA_Server_writeAccessLevel(UA_Server *server, const UA_NodeId nodeId,
  336. const UA_UInt32 accessLevel) {
  337. return __UA_Server_write(server, &nodeId, UA_ATTRIBUTEID_ACCESSLEVEL,
  338. &UA_TYPES[UA_TYPES_UINT32], &accessLevel); }
  339. static UA_INLINE UA_StatusCode
  340. UA_Server_writeMinimumSamplingInterval(UA_Server *server, const UA_NodeId nodeId,
  341. const UA_Double miniumSamplingInterval) {
  342. return __UA_Server_write(server, &nodeId, UA_ATTRIBUTEID_MINIMUMSAMPLINGINTERVAL,
  343. &UA_TYPES[UA_TYPES_DOUBLE], &miniumSamplingInterval); }
  344. static UA_INLINE UA_StatusCode
  345. UA_Server_writeExecutable(UA_Server *server, const UA_NodeId nodeId,
  346. const UA_Boolean executable) {
  347. return __UA_Server_write(server, &nodeId, UA_ATTRIBUTEID_EXECUTABLE,
  348. &UA_TYPES[UA_TYPES_BOOLEAN], &executable); }
  349. /**
  350. * Browsing
  351. * -------- */
  352. UA_BrowseResult UA_EXPORT
  353. UA_Server_browse(UA_Server *server, UA_UInt32 maxrefs, const UA_BrowseDescription *descr);
  354. UA_BrowseResult UA_EXPORT
  355. UA_Server_browseNext(UA_Server *server, UA_Boolean releaseContinuationPoint,
  356. const UA_ByteString *continuationPoint);
  357. #ifndef HAVE_NODEITER_CALLBACK
  358. #define HAVE_NODEITER_CALLBACK
  359. /* Iterate over all nodes referenced by parentNodeId by calling the callback
  360. * function for each child node (in ifdef because GCC/CLANG handle include order
  361. * differently) */
  362. typedef UA_StatusCode (*UA_NodeIteratorCallback)(UA_NodeId childId, UA_Boolean isInverse,
  363. UA_NodeId referenceTypeId, void *handle);
  364. #endif
  365. UA_StatusCode UA_EXPORT
  366. UA_Server_forEachChildNodeCall(UA_Server *server, UA_NodeId parentNodeId,
  367. UA_NodeIteratorCallback callback, void *handle);
  368. #ifdef UA_ENABLE_DISCOVERY
  369. /**
  370. * Discovery
  371. * --------- */
  372. /*
  373. * Register the given server instance at the discovery server.
  374. * This should be called periodically.
  375. * The semaphoreFilePath is optional. If the given file is deleted,
  376. * the server will automatically be unregistered. This could be
  377. * for example a pid file which is deleted if the server crashes.
  378. *
  379. * When the server shuts down you need to call unregister.
  380. */
  381. UA_StatusCode UA_EXPORT
  382. UA_Server_register_discovery(UA_Server *server, const char* discoveryServerUrl, const char* semaphoreFilePath);
  383. /**
  384. * Unregister the given server instance from the discovery server.
  385. * This should only be called when the server is shutting down.
  386. */
  387. UA_StatusCode UA_EXPORT
  388. UA_Server_unregister_discovery(UA_Server *server, const char* discoveryServerUrl);
  389. #endif
  390. /**
  391. * Method Call
  392. * ----------- */
  393. #ifdef UA_ENABLE_METHODCALLS
  394. UA_CallMethodResult UA_EXPORT
  395. UA_Server_call(UA_Server *server, const UA_CallMethodRequest *request);
  396. #endif
  397. /**
  398. * Node Management
  399. * ---------------
  400. *
  401. * Callback Mechanisms
  402. * ^^^^^^^^^^^^^^^^^^^
  403. * There are four mechanisms for callbacks from the node-based information model
  404. * into userspace:
  405. *
  406. * - Datasources for variable nodes, where the variable content is managed
  407. * externally
  408. * - Value-callbacks for variable nodes, where userspace is notified when a
  409. * read/write occurs
  410. * - Object lifecycle management, where a user-defined constructor and
  411. * destructor is added to an object type
  412. * - Method callbacks, where a user-defined method is exposed in the information
  413. * model
  414. *
  415. * Data Source Callback
  416. * ~~~~~~~~~~~~~~~~~~~~
  417. *
  418. * The server has a unique way of dealing with the content of variables. Instead
  419. * of storing a variant attached to the variable node, the node can point to a
  420. * function with a local data provider. Whenever the value attribute is read,
  421. * the function will be called and asked to provide a UA_DataValue return value
  422. * that contains the value content and additional timestamps.
  423. *
  424. * It is expected that the read callback is implemented. The write callback can
  425. * be set to a null-pointer. */
  426. typedef struct {
  427. void *handle; /* A custom pointer to reuse the same datasource functions for
  428. multiple sources */
  429. /* Copies the data from the source into the provided value.
  430. *
  431. * @param handle An optional pointer to user-defined data for the specific data source
  432. * @param nodeid Id of the read node
  433. * @param includeSourceTimeStamp If true, then the datasource is expected to set the source
  434. * timestamp in the returned value
  435. * @param range If not null, then the datasource shall return only a
  436. * selection of the (nonscalar) data. Set
  437. * UA_STATUSCODE_BADINDEXRANGEINVALID in the value if this does not
  438. * apply.
  439. * @param value The (non-null) DataValue that is returned to the client. The
  440. * data source sets the read data, the result status and optionally a
  441. * sourcetimestamp.
  442. * @return Returns a status code for logging. Error codes intended for the
  443. * original caller are set in the value. If an error is returned,
  444. * then no releasing of the value is done. */
  445. UA_StatusCode (*read)(void *handle, const UA_NodeId nodeid,
  446. UA_Boolean includeSourceTimeStamp, const UA_NumericRange *range,
  447. UA_DataValue *value);
  448. /* Write into a data source. The write member of UA_DataSource can be empty
  449. * if the operation is unsupported.
  450. *
  451. * @param handle An optional pointer to user-defined data for the specific data source
  452. * @param nodeid Id of the node being written to
  453. * @param data The data to be written into the data source
  454. * @param range An optional data range. If the data source is scalar or does
  455. * not support writing of ranges, then an error code is returned.
  456. * @return Returns a status code that is returned to the user
  457. */
  458. UA_StatusCode (*write)(void *handle, const UA_NodeId nodeid,
  459. const UA_Variant *data, const UA_NumericRange *range);
  460. } UA_DataSource;
  461. UA_StatusCode UA_EXPORT
  462. UA_Server_setVariableNode_dataSource(UA_Server *server, const UA_NodeId nodeId,
  463. const UA_DataSource dataSource);
  464. /**
  465. * Value Callback
  466. * ~~~~~~~~~~~~~~
  467. * Value Callbacks can be attached to variable and variable type nodes. If
  468. * not-null, they are called before reading and after writing respectively. */
  469. typedef struct {
  470. void *handle;
  471. void (*onRead)(void *handle, const UA_NodeId nodeid,
  472. const UA_Variant *data, const UA_NumericRange *range);
  473. void (*onWrite)(void *handle, const UA_NodeId nodeid,
  474. const UA_Variant *data, const UA_NumericRange *range);
  475. } UA_ValueCallback;
  476. UA_StatusCode UA_EXPORT
  477. UA_Server_setVariableNode_valueCallback(UA_Server *server, const UA_NodeId nodeId,
  478. const UA_ValueCallback callback);
  479. /**
  480. * Object Lifecycle Management Callbacks
  481. * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  482. * Lifecycle management adds constructor and destructor callbacks to
  483. * object types. */
  484. typedef struct {
  485. /* Returns the instance handle that is then attached to the node */
  486. void * (*constructor)(const UA_NodeId instance);
  487. void (*destructor)(const UA_NodeId instance, void *instanceHandle);
  488. } UA_ObjectLifecycleManagement;
  489. UA_StatusCode UA_EXPORT
  490. UA_Server_setObjectTypeNode_lifecycleManagement(UA_Server *server, UA_NodeId nodeId,
  491. UA_ObjectLifecycleManagement olm);
  492. /**
  493. * Method Callbacks
  494. * ~~~~~~~~~~~~~~~~ */
  495. typedef UA_StatusCode (*UA_MethodCallback)(void *methodHandle, const UA_NodeId objectId,
  496. size_t inputSize, const UA_Variant *input,
  497. size_t outputSize, UA_Variant *output);
  498. #ifdef UA_ENABLE_METHODCALLS
  499. UA_StatusCode UA_EXPORT
  500. UA_Server_setMethodNode_callback(UA_Server *server, const UA_NodeId methodNodeId,
  501. UA_MethodCallback method, void *handle);
  502. #endif
  503. /**
  504. * .. _addnodes:
  505. *
  506. * Node Addition and Deletion
  507. * ^^^^^^^^^^^^^^^^^^^^^^^^^^
  508. *
  509. * When creating dynamic node instances at runtime, chances are that you will
  510. * not care about the specific NodeId of the new node, as long as you can
  511. * reference it later. When passing numeric NodeIds with a numeric identifier 0,
  512. * the stack evaluates this as "select a randome free NodeId in that namespace".
  513. * To find out which NodeId was actually assigned to the new node, you may pass
  514. * a pointer `outNewNodeId`, which will (after a successfull node insertion)
  515. * contain the nodeId of the new node. You may also pass NULL pointer if this
  516. * result is not relevant. The namespace index for nodes you create should never
  517. * be 0, as that index is reserved for OPC UA's self-description (namespace 0). */
  518. /* The instantiation callback is used to track the addition of new nodes. It is
  519. * also called for all sub-nodes contained in an object or variable type node
  520. * that is instantiated. */
  521. typedef struct {
  522. UA_StatusCode (*method)(const UA_NodeId objectId, const UA_NodeId typeDefinitionId, void *handle);
  523. void *handle;
  524. } UA_InstantiationCallback;
  525. /* Don't use this function. There are typed versions as inline functions. */
  526. UA_StatusCode UA_EXPORT
  527. __UA_Server_addNode(UA_Server *server, const UA_NodeClass nodeClass,
  528. const UA_NodeId requestedNewNodeId, const UA_NodeId parentNodeId,
  529. const UA_NodeId referenceTypeId, const UA_QualifiedName browseName,
  530. const UA_NodeId typeDefinition, const UA_NodeAttributes *attr,
  531. const UA_DataType *attributeType,
  532. UA_InstantiationCallback *instantiationCallback, UA_NodeId *outNewNodeId);
  533. static UA_INLINE UA_StatusCode
  534. UA_Server_addVariableNode(UA_Server *server, const UA_NodeId requestedNewNodeId,
  535. const UA_NodeId parentNodeId, const UA_NodeId referenceTypeId,
  536. const UA_QualifiedName browseName, const UA_NodeId typeDefinition,
  537. const UA_VariableAttributes attr,
  538. UA_InstantiationCallback *instantiationCallback,
  539. UA_NodeId *outNewNodeId) {
  540. return __UA_Server_addNode(server, UA_NODECLASS_VARIABLE, requestedNewNodeId, parentNodeId,
  541. referenceTypeId, browseName, typeDefinition,
  542. (const UA_NodeAttributes*)&attr,
  543. &UA_TYPES[UA_TYPES_VARIABLEATTRIBUTES],
  544. instantiationCallback, outNewNodeId); }
  545. static UA_INLINE UA_StatusCode
  546. UA_Server_addVariableTypeNode(UA_Server *server, const UA_NodeId requestedNewNodeId,
  547. const UA_NodeId parentNodeId, const UA_NodeId referenceTypeId,
  548. const UA_QualifiedName browseName,
  549. const UA_VariableTypeAttributes attr,
  550. UA_InstantiationCallback *instantiationCallback,
  551. UA_NodeId *outNewNodeId) {
  552. return __UA_Server_addNode(server, UA_NODECLASS_VARIABLETYPE, requestedNewNodeId,
  553. parentNodeId, referenceTypeId, browseName, UA_NODEID_NULL,
  554. (const UA_NodeAttributes*)&attr,
  555. &UA_TYPES[UA_TYPES_VARIABLETYPEATTRIBUTES],
  556. instantiationCallback, outNewNodeId); }
  557. static UA_INLINE UA_StatusCode
  558. UA_Server_addObjectNode(UA_Server *server, const UA_NodeId requestedNewNodeId,
  559. const UA_NodeId parentNodeId, const UA_NodeId referenceTypeId,
  560. const UA_QualifiedName browseName, const UA_NodeId typeDefinition,
  561. const UA_ObjectAttributes attr,
  562. UA_InstantiationCallback *instantiationCallback,
  563. UA_NodeId *outNewNodeId) {
  564. return __UA_Server_addNode(server, UA_NODECLASS_OBJECT, requestedNewNodeId, parentNodeId,
  565. referenceTypeId, browseName, typeDefinition,
  566. (const UA_NodeAttributes*)&attr,
  567. &UA_TYPES[UA_TYPES_OBJECTATTRIBUTES],
  568. instantiationCallback, outNewNodeId); }
  569. static UA_INLINE UA_StatusCode
  570. UA_Server_addObjectTypeNode(UA_Server *server, const UA_NodeId requestedNewNodeId,
  571. const UA_NodeId parentNodeId, const UA_NodeId referenceTypeId,
  572. const UA_QualifiedName browseName,
  573. const UA_ObjectTypeAttributes attr,
  574. UA_InstantiationCallback *instantiationCallback,
  575. UA_NodeId *outNewNodeId) {
  576. return __UA_Server_addNode(server, UA_NODECLASS_OBJECTTYPE, requestedNewNodeId,
  577. parentNodeId, referenceTypeId, browseName, UA_NODEID_NULL,
  578. (const UA_NodeAttributes*)&attr,
  579. &UA_TYPES[UA_TYPES_OBJECTTYPEATTRIBUTES],
  580. instantiationCallback, outNewNodeId); }
  581. static UA_INLINE UA_StatusCode
  582. UA_Server_addViewNode(UA_Server *server, const UA_NodeId requestedNewNodeId,
  583. const UA_NodeId parentNodeId, const UA_NodeId referenceTypeId,
  584. const UA_QualifiedName browseName, const UA_ViewAttributes attr,
  585. UA_InstantiationCallback *instantiationCallback,
  586. UA_NodeId *outNewNodeId) {
  587. return __UA_Server_addNode(server, UA_NODECLASS_VIEW, requestedNewNodeId, parentNodeId,
  588. referenceTypeId, browseName, UA_NODEID_NULL,
  589. (const UA_NodeAttributes*)&attr,
  590. &UA_TYPES[UA_TYPES_VIEWATTRIBUTES],
  591. instantiationCallback, outNewNodeId); }
  592. static UA_INLINE UA_StatusCode
  593. UA_Server_addReferenceTypeNode(UA_Server *server, const UA_NodeId requestedNewNodeId,
  594. const UA_NodeId parentNodeId, const UA_NodeId referenceTypeId,
  595. const UA_QualifiedName browseName,
  596. const UA_ReferenceTypeAttributes attr,
  597. UA_InstantiationCallback *instantiationCallback,
  598. UA_NodeId *outNewNodeId) {
  599. return __UA_Server_addNode(server, UA_NODECLASS_REFERENCETYPE, requestedNewNodeId,
  600. parentNodeId, referenceTypeId, browseName, UA_NODEID_NULL,
  601. (const UA_NodeAttributes*)&attr,
  602. &UA_TYPES[UA_TYPES_REFERENCETYPEATTRIBUTES],
  603. instantiationCallback, outNewNodeId); }
  604. static UA_INLINE UA_StatusCode
  605. UA_Server_addDataTypeNode(UA_Server *server, const UA_NodeId requestedNewNodeId,
  606. const UA_NodeId parentNodeId, const UA_NodeId referenceTypeId,
  607. const UA_QualifiedName browseName, const UA_DataTypeAttributes attr,
  608. UA_InstantiationCallback *instantiationCallback,
  609. UA_NodeId *outNewNodeId) {
  610. return __UA_Server_addNode(server, UA_NODECLASS_DATATYPE, requestedNewNodeId, parentNodeId,
  611. referenceTypeId, browseName, UA_NODEID_NULL,
  612. (const UA_NodeAttributes*)&attr,
  613. &UA_TYPES[UA_TYPES_DATATYPEATTRIBUTES],
  614. instantiationCallback, outNewNodeId); }
  615. UA_StatusCode UA_EXPORT
  616. UA_Server_addDataSourceVariableNode(UA_Server *server, const UA_NodeId requestedNewNodeId,
  617. const UA_NodeId parentNodeId,
  618. const UA_NodeId referenceTypeId,
  619. const UA_QualifiedName browseName,
  620. const UA_NodeId typeDefinition,
  621. const UA_VariableAttributes attr,
  622. const UA_DataSource dataSource, UA_NodeId *outNewNodeId);
  623. #ifdef UA_ENABLE_METHODCALLS
  624. UA_StatusCode UA_EXPORT
  625. UA_Server_addMethodNode(UA_Server *server, const UA_NodeId requestedNewNodeId,
  626. const UA_NodeId parentNodeId, const UA_NodeId referenceTypeId,
  627. const UA_QualifiedName browseName, const UA_MethodAttributes attr,
  628. UA_MethodCallback method, void *handle,
  629. size_t inputArgumentsSize, const UA_Argument* inputArguments,
  630. size_t outputArgumentsSize, const UA_Argument* outputArguments,
  631. UA_NodeId *outNewNodeId);
  632. #endif
  633. UA_StatusCode UA_EXPORT
  634. UA_Server_deleteNode(UA_Server *server, const UA_NodeId nodeId, UA_Boolean deleteReferences);
  635. /**
  636. * Reference Management
  637. * -------------------- */
  638. UA_StatusCode UA_EXPORT
  639. UA_Server_addReference(UA_Server *server, const UA_NodeId sourceId, const UA_NodeId refTypeId,
  640. const UA_ExpandedNodeId targetId, UA_Boolean isForward);
  641. UA_StatusCode UA_EXPORT
  642. UA_Server_deleteReference(UA_Server *server, const UA_NodeId sourceNodeId,
  643. const UA_NodeId referenceTypeId, UA_Boolean isForward,
  644. const UA_ExpandedNodeId targetNodeId, UA_Boolean deleteBidirectional);
  645. #ifdef __cplusplus
  646. }
  647. #endif
  648. #endif /* UA_SERVER_H_ */