libs2opc_server_config.h File Reference

High level interface to configure an OPC UA server. More...

#include <stdbool.h>
#include "sopc_common.h"
#include "sopc_encodeabletype.h"
#include "sopc_types.h"
#include "sopc_user_app_itf.h"

Go to the source code of this file.

Macros
#define	SOPC_DEFAULT_CURRENT_TIME_REFRESH_PERIOD_MS   1000
	Default period value in milliseconds for refreshing the current time value in the Server.ServerStatus.CurrentTime variable node. More...

Typedefs
typedef struct SOPC_ConfigServerXML_Custom	SOPC_ConfigServerXML_Custom
	Structure reserved for future use in order to customize the configuration through XML. e.g.: PKI provider alternative, etc. More...
typedef bool	SOPC_GetServerKeyPassword_Fct(char **outPassword)
	Type of callback to retrieve password for decryption of the server private key. More...
typedef void	SOPC_WriteNotif_Fct(const SOPC_CallContext *callCtxPtr, OpcUa_WriteValue *writeValue, SOPC_StatusCode writeStatus)
	Type of callback to provide to receive write notification on address space. More...
typedef bool	SOPC_CreateMI_NodeAvail_Fct(const SOPC_NodeId *nodeId, OpcUa_NodeClass *outNodeClass, SOPC_StatusCode *outUnavailabilityStatus)
	Type of the callback called by CreateMonitoredItem service when a NodeId is not already part of server address space, the callback result indicates if it shall be considered known by server (and might exist later using AddNode service). More...
typedef void	SOPC_LocalServiceAsyncResp_Fct(SOPC_EncodeableType *type, void *response, uintptr_t userContext)
	Type of callback to provide to receive asynchronous local service response. More...

Functions
SOPC_ReturnStatus	SOPC_ServerConfigHelper_Initialize (void)
	Initializes the S2OPC Server frontend configuration Call to SOPC_ServerConfigHelper_Initialize is required before any other operation and shall be done after a call to SOPC_CommonHelper_Initialize. More...
void	SOPC_ServerConfigHelper_Clear (void)
	Clears the S2OPC Server frontend configuration It shall be done before a call to SOPC_CommonHelper_Clear. More...
SOPC_ReturnStatus	SOPC_ServerConfigHelper_ConfigureFromXML (const char *serverConfigPath, const char *addressSpaceConfigPath, const char *userConfigPath, SOPC_ConfigServerXML_Custom *customConfig)
	Configures server from XML configuration files for: server endpoints, address space and users credential and rights. More...
SOPC_ReturnStatus	SOPC_ServerConfigHelper_SetKeyPasswordCallback (SOPC_GetServerKeyPassword_Fct *getServerKeyPassword)
	Defines the callback to retrieve password for decryption of the server private key. More...
SOPC_ReturnStatus	SOPC_ServerConfigHelper_SetMethodCallManager (SOPC_MethodCallManager *mcm)
	Method Call service configuration. More...
SOPC_ReturnStatus	SOPC_ServerConfigHelper_SetWriteNotifCallback (SOPC_WriteNotif_Fct *writeNotifCb)
	Defines the write notification callback to be used. More...
SOPC_ReturnStatus	SOPC_ServerConfigHelper_SetMonitItemNodeAvailCallback (SOPC_CreateMI_NodeAvail_Fct *nodeAvailCb)
	Defines the callback called by CreateMonitoredItem service when a NodeId is not already part of server. The callback result indicates if it shall be considered known by server (see SOPC_CreateMI_NodeAvail_Fct). More...
SOPC_ReturnStatus	SOPC_ServerConfigHelper_SetLocalServiceAsyncResponse (SOPC_LocalServiceAsyncResp_Fct *asyncRespCb)
	Defines the local service response callback to be used. More...
SOPC_ReturnStatus	SOPC_ServerConfigHelper_SetShutdownCountdown (uint16_t secondsTillShutdown)
	Defines duration of the shutdown phase when stopping the server. More...
SOPC_ReturnStatus	SOPC_ServerConfigHelper_SetCurrentTimeRefreshInterval (uint16_t intervalMs)
	Defines interval in milliseconds used to refresh the server status current time information. More...
SOPC_ReturnStatus	SOPC_HelperConfigServer_Initialize (void)
void	SOPC_HelperConfigServer_Clear (void)
SOPC_ReturnStatus	SOPC_HelperConfigServer_ConfigureFromXML (const char *serverConfigPath, const char *addressSpaceConfigPath, const char *userConfigPath, SOPC_ConfigServerXML_Custom *customConfig)
SOPC_ReturnStatus	SOPC_HelperConfigServer_SetKeyPasswordCallback (SOPC_GetServerKeyPassword_Fct *getServerKeyPassword)
SOPC_ReturnStatus	SOPC_HelperConfigServer_SetMethodCallManager (SOPC_MethodCallManager *mcm)
SOPC_ReturnStatus	SOPC_HelperConfigServer_SetWriteNotifCallback (SOPC_WriteNotif_Fct *writeNotifCb)
SOPC_ReturnStatus	SOPC_HelperConfigServer_SetMonitItemNodeAvailCallback (SOPC_CreateMI_NodeAvail_Fct *nodeAvailCb)
SOPC_ReturnStatus	SOPC_HelperConfigServer_SetLocalServiceAsyncResponse (SOPC_LocalServiceAsyncResp_Fct *asyncRespCb)
SOPC_ReturnStatus	SOPC_HelperConfigServer_SetShutdownCountdown (uint16_t secondsTillShutdown)
SOPC_ReturnStatus	SOPC_HelperConfigServer_SetCurrentTimeRefreshInterval (uint16_t intervalMs)

Detailed Description

High level interface to configure an OPC UA server.

Macro Definition Documentation

SOPC_DEFAULT_CURRENT_TIME_REFRESH_PERIOD_MS

#define SOPC_DEFAULT_CURRENT_TIME_REFRESH_PERIOD_MS   1000

Default period value in milliseconds for refreshing the current time value in the Server.ServerStatus.CurrentTime variable node.

Typedef Documentation

SOPC_ConfigServerXML_Custom

typedef struct SOPC_ConfigServerXML_Custom SOPC_ConfigServerXML_Custom

Structure reserved for future use in order to customize the configuration through XML. e.g.: PKI provider alternative, etc.

SOPC_GetServerKeyPassword_Fct

typedef bool SOPC_GetServerKeyPassword_Fct(char **outPassword)

Type of callback to retrieve password for decryption of the server private key.

Parameters

[out]

outPassword

out parameter, the newly allocated password which shall be a zero-terminated string in case of success.

Returns

true in case of success, otherwise false.

Warning

The implementation of the user callback must free the outPassword and set it back to NULL in case of failure.

SOPC_WriteNotif_Fct

typedef void SOPC_WriteNotif_Fct(const SOPC_CallContext *callCtxPtr, OpcUa_WriteValue *writeValue, SOPC_StatusCode writeStatus)

Type of callback to provide to receive write notification on address space.

Parameters

callCtxPtr	Context provided by server, see getters available (SOPC_CallContext_GetUser, etc.)
writeValue	The value resulting from the write operation in case of write success, or the value requested to be written in case of failure
writeStatus	The service resulting status code for the write value operation requested

Note

Value resulting from write operation might be different from the write value requested since it is possible to request partial write in arrays and strings. Thus it indicates the complete final value here in case of success.

Warning

The callback function shall not do anything blocking or long treatment since it will block any other callback call (other instance of write notification, local service sync/async response, etc.).

SOPC_CreateMI_NodeAvail_Fct

typedef bool SOPC_CreateMI_NodeAvail_Fct(const SOPC_NodeId *nodeId, OpcUa_NodeClass *outNodeClass, SOPC_StatusCode *outUnavailabilityStatus)

Type of the callback called by CreateMonitoredItem service when a NodeId is not already part of server address space, the callback result indicates if it shall be considered known by server (and might exist later using AddNode service).

It returns true when CreateMonitoredItem for this nodeId shall succeed, in this case outNodeClass shall be set to the expected NodeClass and outBadStatus shall be set with an appropriate Bad StatusCode returned in the Publish response as first value notification. It returns false otherwise, in this case server will return Bad_NodeIdUnknown in the CreateMonitoredItem response.

Warning

This callback shall not block the thread that calls it, and shall return immediately.

Parameters

	nodeId	NodeId that is not part of the server address space yet and which is requested in a MonitoredItemCreateRequest. It might be added by AddNode service later.
[out]	outNodeClass	The NodeClass of the known node when it will be available. It shall always be the same for the same NodeId.
[out]	outBadStatus	The appropriate Bad StatusCode to return in the Publish response. OpcUa_BadDataUnavailable or OpcUa_BadWouldBlock are recommended.

Returns

true when CreateMonitoredItem for this nodeId shall succeed, false otherwise.

SOPC_LocalServiceAsyncResp_Fct

typedef void SOPC_LocalServiceAsyncResp_Fct(SOPC_EncodeableType *type, void *response, uintptr_t userContext)

Type of callback to provide to receive asynchronous local service response.

Parameters

response

An asynchronous response to a local service request sent using SOPC_ServerHelper_LocalServiceAsync (see authorized requests). Response will be a pointer to one of the following types: OpcUa_ReadResponse OpcUa_WriteResponse OpcUa_BrowseResponse OpcUa_GetEndpointsResponse OpcUa_FindServersResponse OpcUa_FindServersOnNetworkResponse OpcUa_RegisterServer2Response In case of service failure the response type is always OpcUa_ServiceFault, in this case the response.encodeableType points to OpcUa_ServiceFault_EncodeableType and SOPC_IsGoodStatus(response.ResponseHeader.ServiceResult) is false.

userContext

The context that was provided with the corresponding request provided on SOPC_ServerHelper_LocalServiceAsync call

Warning

The callback function shall not do anything blocking or long treatment since it will block any other callback call (other instance of response, write notification, etc.).

Function Documentation

SOPC_ServerConfigHelper_Initialize()

SOPC_ReturnStatus SOPC_ServerConfigHelper_Initialize

(

void

)

Initializes the S2OPC Server frontend configuration Call to SOPC_ServerConfigHelper_Initialize is required before any other operation and shall be done after a call to SOPC_CommonHelper_Initialize.

The default log configuration is provided by the SOPC_Common_GetDefaultLogConfiguration function in sopc_common.c.
By default, the log configuration is :
.logLevel = SOPC_LOG_LEVEL_INFO
.logSystem = SOPC_LOG_SYSTEM_FILE
.logSysConfig = {.fileSystemLogConfig = {.logDirPath = "", .logMaxBytes = 1048576, .logMaxFiles = 50}}

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_STATE in case of double initialization.

SOPC_ServerConfigHelper_Clear()

void SOPC_ServerConfigHelper_Clear

(

void

)

Clears the S2OPC Server frontend configuration It shall be done before a call to SOPC_CommonHelper_Clear.

SOPC_ServerConfigHelper_ConfigureFromXML()

SOPC_ReturnStatus SOPC_ServerConfigHelper_ConfigureFromXML	(	const char *	serverConfigPath,
		const char *	addressSpaceConfigPath,
		const char *	userConfigPath,
		SOPC_ConfigServerXML_Custom *	customConfig
	)

Configures server from XML configuration files for: server endpoints, address space and users credential and rights.

If not used or used partially, see libs2opc_server_config_custom.h to manually configure through API.

Parameters

serverConfigPath	path to server configuration XML file (s2opc_clientserver_config.xsd schema) or NULL for manual configuration.
addressSpaceConfigPath	path to address space configuration XML file (UANodeSet.xsd schema) or NULL for manual configuration.
userConfigPath	path to users credential and rights configuration XML file (s2opc_clientserver_users_config.xsd schema) or NULL for manual configuration.
customConfig	shall be NULL. Reserved for future customization of configuration from XML (PKI provider, etc.).

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if a path is invalid or all paths are NULL or SOPC_STATUS_INVALID_STATE if the configuration is not possible (toolkit not initialized, server already started).

Note

if S2OPC_EVENT_MANAGEMENT is defined, the available OPC UA event types are initialized from the address space content after calling this function.

SOPC_ServerConfigHelper_SetKeyPasswordCallback()

SOPC_ReturnStatus SOPC_ServerConfigHelper_SetKeyPasswordCallback

(

SOPC_GetServerKeyPassword_Fct *

getServerKeyPassword

)

Defines the callback to retrieve password for decryption of the server private key.

This is optional but if used it shall be defined before starting server and loading its configuration.

Parameters

getServerKeyPassword

The callback to retrieve the password

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if getServerKeyPassword is invalid or SOPC_STATUS_INVALID_STATE if the configuration is not possible (toolkit not initialized, server already started).

Note

This function must be called after the initialization functions of the server library. When the callback is configured, it is called during call to SOPC_ServerConfigHelper_SetKeyCertPairFromPath or SOPC_ServerConfigHelper_ConfigureFromXML.

SOPC_ServerConfigHelper_SetMethodCallManager()

SOPC_ReturnStatus SOPC_ServerConfigHelper_SetMethodCallManager

(

SOPC_MethodCallManager *

mcm

)

Method Call service configuration.

It can be instantiated with SOPC_MethodCallManager_Create() or specific code by applicative code.

Parameters

mcm	A manager to implement method behavior for method nodes that can be used by CallMethod. It shall be compliant with struct SOPC_MethodCallManager of sopc_call_method_manager.h, SOPC_MethodCallManager_Create() provides a default implementation.

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if mcm is invalid or SOPC_STATUS_INVALID_STATE if the configuration is not possible (toolkit not initialized, server already started).

SOPC_ServerConfigHelper_SetWriteNotifCallback()

SOPC_ReturnStatus SOPC_ServerConfigHelper_SetWriteNotifCallback

(

SOPC_WriteNotif_Fct *

writeNotifCb

)

Defines the write notification callback to be used.

This is optional but if used it shall be defined before starting server.

Parameters

writeNotifCb

The write notification callback to be used

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if writeNotifCb is invalid or SOPC_STATUS_INVALID_STATE if the configuration is not possible (toolkit not initialized, server already started).

Warning

The callback function shall not do anything blocking or long treatment since it will block any other callback call (other instance of write notification, local service sync/async response, etc.).

SOPC_ServerConfigHelper_SetMonitItemNodeAvailCallback()

SOPC_ReturnStatus SOPC_ServerConfigHelper_SetMonitItemNodeAvailCallback

(

SOPC_CreateMI_NodeAvail_Fct *

nodeAvailCb

)

Defines the callback called by CreateMonitoredItem service when a NodeId is not already part of server. The callback result indicates if it shall be considered known by server (see SOPC_CreateMI_NodeAvail_Fct).

This is optional but if used it shall be defined before starting server.

Parameters

nodeAvailCb

The MonitoredItem node availability callback to be used by server

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if nodeAvailCb is invalid or SOPC_STATUS_INVALID_STATE if the configuration is not possible (toolkit not initialized, server already started).

Warning

This callback shall not block the thread that calls it, and shall return immediately.

SOPC_ServerConfigHelper_SetLocalServiceAsyncResponse()

SOPC_ReturnStatus SOPC_ServerConfigHelper_SetLocalServiceAsyncResponse

(

SOPC_LocalServiceAsyncResp_Fct *

asyncRespCb

)

Defines the local service response callback to be used.

This is optional if not used or only synchronous version used. This shall be defined before starting the server and using SOPC_ServerHelper_LocalServiceAsync.

Parameters

asyncRespCb

The local service asynchronous response callback to be used

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if asyncRespCb is invalid or SOPC_STATUS_INVALID_STATE if the configuration is not possible (toolkit not initialized, server already started).

Warning

The callback function shall not do anything blocking or long treatment since it will block any other callback call (other instance of write notification, local service sync/async response, etc.).

SOPC_ServerConfigHelper_SetShutdownCountdown()

SOPC_ReturnStatus SOPC_ServerConfigHelper_SetShutdownCountdown

(

uint16_t

secondsTillShutdown

)

Defines duration of the shutdown phase when stopping the server.

According to OPC UA standard the server shall indicate state change and seconds remaining until shutdown during shutdown phase and before actually stopping.

Parameters

secondsTillShutdown

The number of seconds of the shutdown phase prior to actually stopping server

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_STATE if the configuration is not possible (toolkit not initialized, server already started).

Note

Default value is SOPC_DEFAULT_SHUTDOWN_PHASE_IN_SECONDS (5 seconds) if not set. Value 0 should not be used for OPC UA certification compliance.

SOPC_ServerConfigHelper_SetCurrentTimeRefreshInterval()

SOPC_ReturnStatus SOPC_ServerConfigHelper_SetCurrentTimeRefreshInterval

(

uint16_t

intervalMs

)

Defines interval in milliseconds used to refresh the server status current time information.

Parameters

intervalMs

The frequency used to refresh the server status current time information. It might be set to 0 to deactivate the Server.ServerStatus.CurrentTime value update.

Returns

SOPC_STATUS_OK in case of success, SOPC_INVALID_PARAMETER in case the value is less than minimum interval defined by 2 times SOPC_TIMER_RESOLUTION_MS. Otherwise SOPC_STATUS_INVALID_STATE if the configuration is not possible (toolkit not initialized, server already started).

Note

Default value is SOPC_DEFAULT_CURRENT_TIME_REFRESH_PERIOD_MS (1 second) if not set.

SOPC_HelperConfigServer_Initialize()

SOPC_ReturnStatus SOPC_HelperConfigServer_Initialize

(

void

)

Deprecated:

Use SOPC_ServerConfigHelper_Initialize instead

SOPC_HelperConfigServer_Clear()

void SOPC_HelperConfigServer_Clear

(

void

)

Deprecated:

Use SOPC_ServerConfigHelper_Clear instead

SOPC_HelperConfigServer_ConfigureFromXML()

SOPC_ReturnStatus SOPC_HelperConfigServer_ConfigureFromXML	(	const char *	serverConfigPath,
		const char *	addressSpaceConfigPath,
		const char *	userConfigPath,
		SOPC_ConfigServerXML_Custom *	customConfig
	)

Deprecated:

Use SOPC_ServerConfigHelper_ConfigureFromXML instead

SOPC_HelperConfigServer_SetKeyPasswordCallback()

SOPC_ReturnStatus SOPC_HelperConfigServer_SetKeyPasswordCallback

(

SOPC_GetServerKeyPassword_Fct *

getServerKeyPassword

)

Deprecated:

Use SOPC_ServerConfigHelper_SetKeyPasswordCallback instead

SOPC_HelperConfigServer_SetMethodCallManager()

SOPC_ReturnStatus SOPC_HelperConfigServer_SetMethodCallManager

(

SOPC_MethodCallManager *

mcm

)

Deprecated:

Use SOPC_ServerConfigHelper_SetMethodCallManager instead

SOPC_HelperConfigServer_SetWriteNotifCallback()

SOPC_ReturnStatus SOPC_HelperConfigServer_SetWriteNotifCallback

(

SOPC_WriteNotif_Fct *

writeNotifCb

)

Deprecated:

Use SOPC_ServerConfigHelper_SetWriteNotifCallback instead

SOPC_HelperConfigServer_SetMonitItemNodeAvailCallback()

SOPC_ReturnStatus SOPC_HelperConfigServer_SetMonitItemNodeAvailCallback

(

SOPC_CreateMI_NodeAvail_Fct *

nodeAvailCb

)

Deprecated:

Use SOPC_ServerConfigHelper_SetMonitItemNodeAvailCallback instead

SOPC_HelperConfigServer_SetLocalServiceAsyncResponse()

SOPC_ReturnStatus SOPC_HelperConfigServer_SetLocalServiceAsyncResponse

(

SOPC_LocalServiceAsyncResp_Fct *

asyncRespCb

)

Deprecated:

Use SOPC_ServerConfigHelper_SetLocalServiceAsyncResponse instead

SOPC_HelperConfigServer_SetShutdownCountdown()

SOPC_ReturnStatus SOPC_HelperConfigServer_SetShutdownCountdown

(

uint16_t

secondsTillShutdown

)

Deprecated:

Use SOPC_ServerConfigHelper_SetShutdownCountdown instead

SOPC_HelperConfigServer_SetCurrentTimeRefreshInterval()

SOPC_ReturnStatus SOPC_HelperConfigServer_SetCurrentTimeRefreshInterval

(

uint16_t

intervalMs

)

Deprecated:

Use SOPC_ServerConfigHelper_SetCurrentTimeRefreshInterval instead