ua_server.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283
  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_types.h"
  21. #include "ua_types_generated.h"
  22. #include "ua_nodeids.h"
  23. #include "ua_connection.h"
  24. #include "ua_log.h"
  25. /**
  26. * @defgroup server Server
  27. *
  28. * @{
  29. */
  30. struct UA_Server;
  31. typedef struct UA_Server UA_Server;
  32. UA_Server UA_EXPORT * UA_Server_new(void);
  33. void UA_EXPORT UA_Server_setServerCertificate(UA_Server *server, UA_ByteString certificate);
  34. void UA_EXPORT UA_Server_delete(UA_Server *server);
  35. /** Sets the logger used by the server */
  36. void UA_EXPORT UA_Server_setLogger(UA_Server *server, UA_Logger logger);
  37. /**
  38. * Runs the main loop of the server. In each iteration, this calls into the
  39. * networklayers to see if work have arrived and checks if timed events need to
  40. * be triggered.
  41. *
  42. * @param server The server object
  43. * @param nThreads The number of worker threads. Is ignored if MULTITHREADING is
  44. * not activated.
  45. * @param running Points to a booloean value on the heap. When running is set to
  46. * false, the worker threads and the main loop close and the server is shut
  47. * down.
  48. * @return Indicates whether the server shut down cleanly
  49. *
  50. */
  51. UA_StatusCode UA_EXPORT UA_Server_run(UA_Server *server, UA_UInt16 nThreads, UA_Boolean *running);
  52. /** @brief A datasource is the interface to interact with a local data provider.
  53. *
  54. * Implementors of datasources need to provide functions for the callbacks in
  55. * this structure. After every read, the handle needs to be released to indicate
  56. * that the pointer is no longer accessed. As a rule, datasources are never
  57. * copied, but only their content. The only way to write into a datasource is
  58. * via the write-service.
  59. *
  60. * It is expected that the read and release callbacks are implemented. The write
  61. * callback can be set to null.
  62. **/
  63. typedef struct {
  64. const void *handle;
  65. UA_StatusCode (*read)(const void *handle, UA_DataValue *value);
  66. void (*release)(const void *handle, UA_DataValue *value);
  67. UA_StatusCode (*write)(const void *handle, const UA_Variant *data);
  68. } UA_DataSource;
  69. /** Add a reference to the server's address space */
  70. UA_StatusCode UA_EXPORT UA_Server_addReference(UA_Server *server, const UA_AddReferencesItem *item);
  71. UA_StatusCode UA_EXPORT UA_Server_addVariableNode(UA_Server *server, UA_Variant *value, UA_NodeId *nodeId,
  72. UA_QualifiedName *browseName, const UA_NodeId *parentNodeId,
  73. const UA_NodeId *referenceTypeId);
  74. UA_StatusCode UA_EXPORT UA_Server_addDataSourceVariableNode(UA_Server *server, UA_DataSource dataSource,
  75. UA_NodeId *nodeId, UA_QualifiedName *browseName,
  76. const UA_NodeId *parentNodeId,
  77. const UA_NodeId *referenceTypeId);
  78. /** Work that is run in the main loop (singlethreaded) or dispatched to a worker
  79. thread. */
  80. typedef struct UA_WorkItem {
  81. enum {
  82. UA_WORKITEMTYPE_NOTHING,
  83. UA_WORKITEMTYPE_BINARYNETWORKMESSAGE,
  84. UA_WORKITEMTYPE_METHODCALL,
  85. UA_WORKITEMTYPE_DELAYEDMETHODCALL,
  86. } type;
  87. union {
  88. struct {
  89. UA_Connection *connection;
  90. UA_ByteString message;
  91. } binaryNetworkMessage;
  92. struct {
  93. void * data;
  94. void (*method)(UA_Server *server, void *data);
  95. } methodCall;
  96. } work;
  97. } UA_WorkItem;
  98. /**
  99. * @param server The server object.
  100. *
  101. * @param work Pointer to the WorkItem that shall be added. The pointer is not
  102. * freed but copied to an internal representation.
  103. *
  104. * @param executionTime The time when the work shall be executed. If the time lies in the
  105. * past, the work will be executed in the next iteration of the server's
  106. * main loop
  107. *
  108. * @param resultWorkGuid Upon success, the pointed value is set to the guid of
  109. * the workitem in the server queue. This can be used to cancel the work
  110. * later on. If the pointer is null, the guid is not set.
  111. *
  112. * @return Upon sucess, UA_STATUSCODE_GOOD is returned. An error code otherwise.
  113. */
  114. UA_StatusCode UA_EXPORT UA_Server_addTimedWorkItem(UA_Server *server, const UA_WorkItem *work,
  115. UA_DateTime executionTime, UA_Guid *resultWorkGuid);
  116. /**
  117. * @param server The server object.
  118. *
  119. * @param work Pointer to the WorkItem that shall be added. The pointer is not
  120. * freed but copied to an internal representation.
  121. *
  122. * @param interval The work that is executed repeatedly with the given interval
  123. * (in 100ns). If work with the same repetition interval already exists,
  124. * the first execution might occur sooner.
  125. *
  126. * @param resultWorkGuid Upon success, the pointed value is set to the guid of
  127. * the workitem in the server queue. This can be used to cancel the work
  128. * later on. If the pointer is null, the guid is not set.
  129. *
  130. * @return Upon sucess, UA_STATUSCODE_GOOD is returned. An error code otherwise.
  131. */
  132. UA_StatusCode UA_EXPORT UA_Server_addRepeatedWorkItem(UA_Server *server, const UA_WorkItem *work,
  133. UA_UInt32 interval, UA_Guid *resultWorkGuid);
  134. /** Remove timed or repeated work */
  135. UA_Boolean UA_EXPORT UA_Server_removeWorkItem(UA_Server *server, UA_Guid workId);
  136. /**
  137. * Interface to the binary network layers. This structure is returned from the
  138. * function that initializes the network layer. The layer is already bound to a
  139. * specific port and listening. The functions in the structure are never called
  140. * in parallel but only sequentially from the server's main loop. So the network
  141. * layer does not need to be thread-safe.
  142. */
  143. typedef struct {
  144. void *nlHandle;
  145. /**
  146. * Starts listening on the the networklayer.
  147. *
  148. * @return Returns UA_STATUSCODE_GOOD or an error code.
  149. */
  150. UA_StatusCode (*start)(void *nlHandle, UA_Logger *logger);
  151. /**
  152. * Gets called from the main server loop and returns the work that
  153. * accumulated (messages and close events) for dispatch. The networklayer
  154. * does not wait on connections but returns immediately the work that
  155. * accumulated.
  156. *
  157. * @param workItems When the returned integer is positive, *workItems points
  158. * to an array of WorkItems of the returned size.
  159. * @param timeout The timeout during which an event must arrive.
  160. * @return The size of the returned workItems array. If the result is
  161. * negative, an error has occured.
  162. */
  163. UA_Int32 (*getWork)(void *nlhandle, UA_WorkItem **workItems, UA_UInt16 timeout);
  164. /**
  165. * Closes the network connection and returns all the work that needs to
  166. * be finished before the network layer can be safely deleted.
  167. *
  168. * @param workItems When the returned integer is positive, *workItems points
  169. * to an array of WorkItems of the returned size.
  170. * @return The size of the returned workItems array. If the result is
  171. * negative, an error has occured.
  172. */
  173. UA_Int32 (*stop)(void *nlhandle, UA_WorkItem **workItems);
  174. /** Deletes the network layer. Call only after a successfull shutdown. */
  175. void (*free)(void *nlhandle);
  176. } UA_ServerNetworkLayer;
  177. /**
  178. * Adds a network layer to the server. The network layer is destroyed together
  179. * with the server. Do not use it after adding it as it might be moved around on
  180. * the heap.
  181. */
  182. void UA_EXPORT UA_Server_addNetworkLayer(UA_Server *server, UA_ServerNetworkLayer networkLayer);
  183. /** @} */
  184. /**
  185. * @ingroup nodestore
  186. *
  187. * @defgroup external_nodestore External Nodestore
  188. *
  189. * @brief An external application that manages its own data and data model
  190. *
  191. * To plug in outside data sources, one can use
  192. *
  193. * - VariableNodes with a data source (functions that are called for read and write access)
  194. * - An external nodestore that is mapped to specific namespaces
  195. *
  196. * If no external nodestore is defined for a nodeid, it is always looked up in
  197. * the "local" nodestore of open62541. Namespace Zero is always in the local
  198. * nodestore.
  199. *
  200. * @{
  201. */
  202. typedef UA_Int32 (*UA_ExternalNodeStore_addNodes)
  203. (void *ensHandle, const UA_RequestHeader *requestHeader, UA_AddNodesItem *nodesToAdd, UA_UInt32 *indices,
  204. UA_UInt32 indicesSize, UA_AddNodesResult* addNodesResults, UA_DiagnosticInfo *diagnosticInfos);
  205. typedef UA_Int32 (*UA_ExternalNodeStore_addReferences)
  206. (void *ensHandle, const UA_RequestHeader *requestHeader, UA_AddReferencesItem* referencesToAdd,
  207. UA_UInt32 *indices,UA_UInt32 indicesSize, UA_StatusCode *addReferencesResults,
  208. UA_DiagnosticInfo *diagnosticInfos);
  209. typedef UA_Int32 (*UA_ExternalNodeStore_deleteNodes)
  210. (void *ensHandle, const UA_RequestHeader *requestHeader, UA_DeleteNodesItem *nodesToDelete, UA_UInt32 *indices,
  211. UA_UInt32 indicesSize, UA_StatusCode *deleteNodesResults, UA_DiagnosticInfo *diagnosticInfos);
  212. typedef UA_Int32 (*UA_ExternalNodeStore_deleteReferences)
  213. (void *ensHandle, const UA_RequestHeader *requestHeader, UA_DeleteReferencesItem *referenceToDelete,
  214. UA_UInt32 *indices, UA_UInt32 indicesSize, UA_StatusCode deleteReferencesresults,
  215. UA_DiagnosticInfo *diagnosticInfos);
  216. typedef UA_Int32 (*UA_ExternalNodeStore_readNodes)
  217. (void *ensHandle, const UA_RequestHeader *requestHeader, UA_ReadValueId *readValueIds, UA_UInt32 *indices,
  218. UA_UInt32 indicesSize,UA_DataValue *readNodesResults, UA_Boolean timeStampToReturn,
  219. UA_DiagnosticInfo *diagnosticInfos);
  220. typedef UA_Int32 (*UA_ExternalNodeStore_writeNodes)
  221. (void *ensHandle, const UA_RequestHeader *requestHeader, UA_WriteValue *writeValues, UA_UInt32 *indices,
  222. UA_UInt32 indicesSize, UA_StatusCode *writeNodesResults, UA_DiagnosticInfo *diagnosticInfo);
  223. typedef UA_Int32 (*UA_ExternalNodeStore_browseNodes)
  224. (void *ensHandle, const UA_RequestHeader *requestHeader, UA_BrowseDescription *browseDescriptions,
  225. UA_UInt32 *indices, UA_UInt32 indicesSize, UA_UInt32 requestedMaxReferencesPerNode,
  226. UA_BrowseResult *browseResults, UA_DiagnosticInfo *diagnosticInfos);
  227. typedef UA_Int32 (*UA_ExternalNodeStore_delete)(void *ensHandle);
  228. typedef struct UA_ExternalNodeStore {
  229. void *ensHandle;
  230. UA_ExternalNodeStore_addNodes addNodes;
  231. UA_ExternalNodeStore_deleteNodes deleteNodes;
  232. UA_ExternalNodeStore_writeNodes writeNodes;
  233. UA_ExternalNodeStore_readNodes readNodes;
  234. UA_ExternalNodeStore_browseNodes browseNodes;
  235. UA_ExternalNodeStore_addReferences addReferences;
  236. UA_ExternalNodeStore_deleteReferences deleteReferences;
  237. UA_ExternalNodeStore_delete destroy;
  238. } UA_ExternalNodeStore;
  239. UA_StatusCode UA_EXPORT
  240. UA_Server_addExternalNamespace(UA_Server *server, UA_UInt16 namespaceIndex, const UA_String *url, UA_ExternalNodeStore *nodeStore);
  241. /** @} */
  242. #ifdef __cplusplus
  243. } // extern "C"
  244. #endif
  245. #endif /* UA_SERVER_H_ */