ANSI C Based OPC UA Client/Server SDK  1.9.0.430
Configuring the SDK

Overview

When building the SDK using CMake, it can be configured in a number of ways using the CMake options described below.

Note
Please read the section UaStack carefully if the SDK is used in a multithreaded application.

SDK Configuration

The following options influence whether the SDK and/or the UaStack are built as shared libraries or statically.

BUILD_SHARED_STACK
Build the UaStack as a shared library.
BUILD_SHARED_LIBS
Build the SDK and all of its modules as shared libraries.

Base Library Configuration

The following options affect the base library which is needed for Client and Server SDK:

BUILD_UABASEC
Enable building the base library.
UABASE_ENABLE_ERROR_LOOKUP
Enable the utility function UaBase_StatusCode_ToString.
UABASE_SETTINGS_USE_FILEBACKEND
Use the file backend for UaBase_Settings. Currently this is the only supported backend.
UABASE_USE_FILESYSTEM
All functions using a file system can be disabled using this option.

Server SDK Configuration

The following options affect the Server SDK library:

BUILD_UASERVERC
Enable building the Server SDK.
BUILD_AUTH_INTERNAL, BUILD_AUTH_INTERNAL_EX, BUILD_AUTH_WIN32, BUILD_AUTH_PAM, BUILD_AUTH_SASL, BUILD_AUTH_USER
Enables the respective Authentication module.
BUILD_AUTHORIZATION
Enable the Authorization module. At least one authentication module has to be enabled to use authorization.
BUILD_DI_PROVIDER
Enable the DI address space in the SDK.
BUILD_PLCOPEN_PROVIDER
Enable the PLCopen address space in the SDK.
UASERVER_CALL
Enable the UA method call service (examples can be found in Lesson 4: Adding Support for Methods).
UASERVER_EVENTS
Enable the alarms & events module of the SDK (examples can be found in Lesson 5: Adding Support for Events and Lesson 6: Adding Support for Alarms & Conditions).
UASERVER_HISTORYREAD
Enable the UA history read service (examples can be found in Lesson 7: Adding Support for Historical Access).
UASERVER_HISTORYUPDATE
Enable the UA history update service.
UASERVER_NODEMANAGEMENT
Enable the UA node management services (Add/DeleteNodes, Add/DeleteReferences).
UASERVER_QUERY
Enable the UA query services (QueryFirst/Next).
BUILD_WITH_DISCOVERY
Enable support for registering at an LDS.
BUILD_WITH_UNITS
Enable the utility functions UaServer_EUInformationFromUnitId, UaServer_CommonCodeFromUnitId, and UaServer_UnitIdFromCommonCode.
UASERVER_GDS_PUSH
Enable the GDS push model implementation.
UASERVER_AUDITING
Enable the generation of audit events by the SDK.
UASERVER_ENABLE_DESCRIPTIONS
Enables the description node attribute. Disable to save space by omitting the description strings.
UASERVER_ENABLE_ARRAYDIMENSIONS_CHECK
Match write values against the variable's array dimensions and return an error if the value is too big.
UASERVER_ENABLE_MINSAMPLINGINTERVAL
Enables the optional variable attribute MinimumSamplingInterval.

Client SDK Configuration

The following options affect the Client SDK library:

BUILD_UACLIENTC
Enable building the Client SDK.

UaStack

The UaStack can also be configured in a number of ways, especially the options regarding synchronization and timers have to be set carefully.

Note
If any of the SDK’s callback functions (UaServer_ReadComplete, UaServer_WriteComplete etc., UaServer_NewItemValue) are called from another thread than the SDK’s main thread (the one calling UaBase_DoCom), UASTACK_USE_SYNCHRONIZATION has to be enabled.
UASTACK_USE_SYNCHRONIZATION
Build the UaStack with synchronization support.
UASTACK_HAVE_THREADS
Build the UaStack with thread and threadpool support.
UASTACK_USE_TRACE_RAW
Enable the unfiltered trace API. Needed for trace events and for tracing the trace level to console and file.
UASTACK_CLIENTAPI_ENABLED
Enable the client API of the UaStack. This option has to be ON if the SDK is built with BUILD_WITH_DISCOVERY or when building the Client SDK.
UASTACK_SERVERAPI_ENABLED
Enable the server API of the UaStack. This option has to be ON when building the Server SDK.

The following options configure the security and encryption abilities of the UaStack.

UASTACK_WITH_OPENSSL
Enable support for encryption, signing and PKI certificates.
UASTACK_SUPPORT_SECURITYPOLICY_NONE
Enable support for the None security policy.
UASTACK_SUPPORT_SECURITYPOLICY_BASIC128RSA15
Enable support for the deprecated Basic128Rsa15 security policy. Only available if UASTACK_WITH_OPENSSL is set to ON.
UASTACK_SUPPORT_SECURITYPOLICY_BASIC256
Enable support for the deprecated Basic256 security policy. Only available if UASTACK_WITH_OPENSSL is set to ON.
UASTACK_SUPPORT_SECURITYPOLICY_BASIC256SHA256
Enable support for the Basic256Sha256 security policy. Only available if UASTACK_WITH_OPENSSL is set to ON.
UASTACK_SUPPORT_SECURITYPOLICY_AES128SHA256RSAOAEP
Enable support for the Aes128Sha256RsaOaep security policy. Only available if UASTACK_WITH_OPENSSL is set to ON. Only available for OpenSSL V1.0.0 or later.
UASTACK_SUPPORT_SECURITYPOLICY_AES256SHA256RSAPSS
Enable support for the Aes256Sha256RsaPss security policy. Only available if UASTACK_WITH_OPENSSL is set to ON. Only available for OpenSSL V1.0.2 or later.

The next set of options enable or disable features in the UaStack, aiming to influence the resulting code and binary size of the UaStack.

UASTACK_MINIMAL_DISABLE_TRACE
Disable the trace functionality.
UASTACK_MINIMAL_OMIT_TYPE_NAME
Omit the type name string of encodeable types.
UASTACK_MINIMAL_OMIT_XML_ENCODING
Omit the XML encoding id in encodeable types.
UASTACK_MINIMAL_SMALL_DATAVALUE
Reduce the size of OpcUa_DataValue by removing the picoseconds in timestamps.
UASTACK_WITH_SIMPLE_BINARYENCODER_API
Enable simple binary encoder API.

There are three advanced CMake options influencing the number of connections that can be created to/from the SDK. You can show them by checking the “Advanced” check box in the CMake GUI.

The following values are the minimum required amounts of resources for the targeted functionality, so a reserve should be included when setting the values.

UASTACK_TCPLISTENER_MAX_CONNECTIONS
Server only: desired maximum number of connections per endpoint.
UASTACK_SOCKETMANAGER_NUMBER_OF_SOCKETS
Server: one internal socket plus the total number of sockets needed for all endpoints. The number of sockets per endpoint is UASTACK_TCPLISTENER_MAX_CONNECTIONS plus 2 (one listen socket and one reserved socket). Thus, if the server provides E endpoints, each accepting C connections, UASTACK_SOCKETMANAGER_NUMBER_OF_SOCKETS is
1 + [E * (2 + C)]
More information can be found below.
Client: one internal socket plus the desired maximum number of connections
See Notes on UASTACK_SOCKETMANAGER_NUMBER_OF_SOCKETS for applications that have both client and server functionality.
UASTACK_NUMBER_OF_AVAILABLE_TIMERS
The SDK including the UaStack needs up to 15 timers. The number of timers used by the providers (for subscription handling) and by the application have to be added to the numbers calculated from below:
Server: One per configured endpoint;
Client: Two times the desired number of sessions.
For an application that includes both client and server functionality, both values have to be summed up. For example, if the server part should provide three endpoints and the client part should be able to open five connections, UASTACK_NUMBER_OF_AVAILABLE_TIMERS is 15 + 3 + ( 5 * 2 ) = 28.

The following options are only visible after setting the CMake option ENABLE_EXPERIMENTAL_OPTIONS to ON. We do not recommend to change any of these options.

ENABLE_STATIC_CRT
Build against the static C runtime.
UASTACK_WITH_HTTPS
Enable experimental support for HTTPS.
UASTACK_WITH_TLS
Set this to ON if you enabled UASTACK_WITH_HTTPS.

Notes on UASTACK_SOCKETMANAGER_NUMBER_OF_SOCKETS

The UaStack parameter UASTACK_SOCKETMANAGER_NUMBER_OF_SOCKETS has to be calculated differently for single-threaded and multithreaded mode. The ANSI C SDK only works single-threaded, so this variant will be described below.

In single-threaded mode, an application has only one socketmanager. For a server, this means that we need the required sockets for all endpoints plus one internal socket. Each endpoint requires one socket for each connection plus one listen socket and one reserved socket.

For a client, we need one socket per connection plus one internal socket.

For an application that has both client and server functionality, we need the internal socket only once, and have to add the required sockets for all endpoints of the server part and the number of connections of the client part.

The following figure shows examples for each case. For a server with two endpoints, each accepting four connections, UASTACK_SOCKETMANAGER_NUMBER_OF_SOCKETS is

1 + [2 * (2 + 4)] = 13

For a client that can open three connections, UASTACK_SOCKETMANAGER_NUMBER_OF_SOCKETS is

1 + 3 = 4

For an application that combines the functionality of the aforementioned server and client, UASTACK_SOCKETMANAGER_NUMBER_OF_SOCKETS is

1 + [2 * (2 + 4)] + 3 = 16

socketmanager_numberofsockets.png

Data Logger Library

For historical data access, the data logger library delivered with the SDK can be used. Currently, it is delivered with an example file backend. The following options modify how it is built.

BUILD_DATA_LOGGER
Enables the data logger module (an example can be found in Lesson 7: Adding Support for Historical Access).
BUILD_DATA_LOGGER_FILE_BACKEND
Enables the file backend of the data logger module.
DATA_LOGGER_MAX_DATA_ITEMS
Maximum number of data log items.
DATA_LOGGER_MAX_EVENT_ITEMS
Maximum number of event log items.
DATA_LOGGER_MAX_STRINGNODEID_LENGTH
Maximum length of a string identifier in NodeIds.

Minimal SDK Configuration Example

To reduce the size and resource consumption to a minimum, the following settings are of interest (leave all other settings at default):

BUILD_SHARED_STACK
Set to OFF to integrate the UaStack as static library, reducing the size of the resulting executable code.
UASTACK_MINIMAL_SMALL_VARIANT
Requires ENABLE_EXPERIMENTAL_OPTIONS to be enabled. Reduces the maximum String length to 64 kB, reducing the size of the OpcUa_String structure as well as removing support for Matrix values in OpcUa_Variant.
UASTACK_MINIMAL_SMALL_DATAVALUE
Removes the picoseconds fields from timestamps in OpcUa_DataValue.
UASTACK_MINIMAL_OMIT_TYPE_NAME
Omits typename strings in encodeable type structures.
UASTACK_MINIMAL_DISABLE_TRACE
Disables the trace, removing all trace strings from the code.
UASTACK_USE_SYNCHRONIZATION
Set to OFF if you use the SDK in only one thread.
UASTACK_WITH_OPENSSL, UASTACK_WITH_PKI_WIN32
Set to OFF to remove PKI support and the OpenSSL dependency, disables security.
UASTACK_CLIENTAPI_ENABLED, UASTACK_SERVERAPI_ENABLED
Only enable what is needed.
UABASE_ENABLE_ERROR_LOOKUP
Set to OFF to remove the StatusCode to string table.
UABASE_USE_FILESYSTEM
Set to OFF to remove dependency to a file system. Disables all AUTH options.
BUILD_UACLIENTC, BUILD_UASERVERC
Only enable what is needed.
BUILD_DATA_LOGGER
Set to OFF to remove the data logger module.
BUILD_DI_PROVIDER, BUILD_PLCOPEN_PROVIDER
Only enable what is needed.
BUILD_WITH_DISCOVERY
Set to OFF to remove the discovery module.
BUILD_WITH_UNITS
Set to OFF to remove the UnitId to EUInformation table.
UASERVER_AUDITING, UASERVER_CALL, UASERVER_EVENTS, UASERVER_HISTORYREAD, UASERVER_HISTORYUPDATE, UASERVER_GDS_PUSH
Set all modules that are not needed to OFF.
UASERVER_ENABLE_DESCRIPTIONS
Set to OFF to omit the description attribute of nodes.
CMAKE_BUILD_TYPE
Set to MinSizeRel to create an executable as small as possible.